Стиль программирования, комментарии и строки документации

Про стиль, оформление и т. п. есть целое сообщество: PyCQA

О дисциплине разработки

• Техническая роль: readability counts, в т. ч. со стороны роботов-анализаторов
• Социальная роль: является общественным договором (social contract)
• Не догма: исключения подтверждают правило

Замечание. Многие ссылки в плане приведены через сайт Python Packages Index (PyPI). Получается один лишний уровень косвенности, но:

• Там всегда есть ссылка на домашнюю страницу и репозиторий проекта
• Это позволяет оценить качество интеграции проекта в сообщество

Оформление кода

• pep-0008 — рекомендации к оформлению кода.

• pep-0257 — рекомендации к оформлению строк документации

  • pydoc // help()

  • Использование docstring для разработки (doctest и техническое документирование)

Анализаторы кода (см. сайт PyCQA):

• Основанные на pep-0008+: Flake8: (pycodestyle, PyFlakes, mccabe + другие плагины), Pylint, и более адские: black, …

  • Настройка flake8

  • В частности, max-line-length = 100

• Основанные на pep-0257 (строки документации): pydocstyle

• Статический анализ: Astroid (низкоуровневый), bandit (+безопасность), оценка сложности mccabe (flake8 --max-complexity), частично Pylint

• Особняком mypy — это статическая типизация и компиляция в бинарник (как следствие — статический анализ типов)

  • Много поддержки в современном Python

• …

Форматтеры

• autopep8 (исправление несоответствий с PEP8)

• yapf (+несколько заданных стилей)

• black (один стиль, emoji в командной строке и немножко издевательств)

Регламент или стандарт?

“A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. With consistency a great soul has simply nothing to do. He may as well concern himself with his shadow on the wall. Speak what you think now in hard words, and to-morrow speak what to-morrow thinks in hard words again, though it contradict every thing you said to-day. — 'Ah, so you shall be sure to be misunderstood.' — Is it so bad, then, to be misunderstood? Pythagoras was misunderstood, and Socrates, and Jesus, and Luther, and Copernicus, and Galileo, and Newton, and every pure and wise spirit that ever took flesh. To be great is to be misunderstood.”

• Ralph Waldo Emerson, Self-Reliance, 1841

  • перевод Якова Кротова

• небольшая статья про эту цитату

Примеры дисциплин оформления

• The Hitchhiker’s Guide to Python! (и вся книга огонь, хоть и не новая, но её потихоньку подправляют на гитхабе!)

• The Black code style

• Open edX

• Khan Academy style guide

• Chromium OS autotests style guide

• …

Из личных наблюдений

Что (почти) не покажут анализаторы кода

• Программирование в столбик (mccabe?)

• Программирование копипастой (^C^V-style)

• Лапша (spaghetti code)
• Шланг (overfunctional code) (длина строки разве что)
• Не читатель (python underusage)
  • пасказлизация
  • изобретение велосипедов (не понял/не нашёл — решил написать сам)
• Магические числа

Комментарии

• Не «что» и «как», а «зачем» и «почему»
  • Don't Repeat Youself (DRY) vs Write Everything Twice (WET) ☺
• Комментарии vs. код на Python (это не Си же)
  • ⇒ No code smell: всё, что можно объяснить на Pythn, надо объяснять на Python
• Комментарии vs. строки документации
  • Программист-пользователь VS программист-разрбаотчик

• Выковыривание комментариев с помощью inspect.getcomments() и прочие синтаксические дисциплины

• Literate programming (в русскую WP не смотрим) и прочие семантические дисциплины

Аннотирование и статическая типизация

Напомню:

• controlflow.html

• Лекция прошлого года

• Не входит в список официальных рекомендаций, это часть дисциплины разработки
  • …но очень активно развивается — очевидно, для ведения больших и сверхбольших проектов с низкой информационной доступностью (включая нечитаемые объёмы)
• + Помогает быстро программировать в IDE

• + Усиливает надёжность (при использовании mypy и ему подобных в качестве линтера)

• + Особый вид документации: лучше, чем комментарии про то же самое
• - Плодит лексический шум

Д/З

Напомнить про Д/З вместо фич совместного проекта (одно требование в проекте может отсутсвтовать, но присутствовать в модифицированном решении Д/З)

В семестровом проекте должна быть поддержка

• Проверки стиля оформления с помощью flake8 или pylint

• Проверки стиля оформления docstrings с помощью pydocstyle

  • Если docstrings используются для хранения технической информации — с pydocstyle надо договариваться

В каталоге проекта можно разместить настроечные файлы проверяльщиков и изменить/отключить некоторые из претензии: например, изменить длину строки.