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

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

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

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

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

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

• Хороший, годный перевод: https://pep8.ru/doc/pep8/

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

• pydoc // help()

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

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

• Основанные на pep-0008: pycodestyle, Pylint, Flake8

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

• Статический анализ: Astroid, Bandit, (Baron/RedBaron, но что-то они заглохли немножк)

• …

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

“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

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

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

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

• Неряшливость

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

  • Лапша (spaghetti code)
  • Шланг (overfunctional code)
  • Не читатель (python underusage)
  • Магические числа
• Ошибки проектирования
  • Программирование в столбик
  • Переупрощение (пасказлизация)
  • Переусложнение (лиспизация и т. п.)

Комментарии

• Не «что» и «как», а «зачем» и «почему»
• Комментарии vs. код на Python (это не Си же)
• Комментарии vs. строки документации

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

Аннотирование

Напомню:

• controlflow.html

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

• Не входит (?) в список рекомендаций, это часть дисциплины разработки

Д/З

1. Зарегистрировать свой совместный проект

   • Создать публичный репозиторий

   • Повесить заявку с названием проекта здесь. В заявке указать

     • Ссылку на git-репозиторий с проектом
     • Имена (ФИО, группа) участников
     • Ники, под которыми они коммитят в проект

2. Разработать и опубликовать в репозитории постановку задачи

   • Проще всего описать её в README-файле

3. Разработать и опубликовать в репозитории интерфейсную модель будущего приложения
   • Смысл модели — в том, чтобы я мог оценить объём работ (и мысленно поделить его на количество участников)

   • Если вы разрабатываете не GUI-приложение, какая-то модель всё равно должна быть — проект API, описание каких-то составных частей и их взаимодействия и т. п. Ещё один смысл модели — в том, чтобы вы заранее представляли, что именно будете делать ☺

4. Привести имеющийся код проекта в соответствие с требованиям по стилю

   • Создать настроечный файл, в котором изменить умолчания, если они не соответствуют принятой вами дисциплине разработки