Требования к коду на Python

Требования к коду на Python, действующие в этой книге, рекомендуется соблюдать и в собственных проектах:

  • Строгое соответствие PEP 8.
  • Длина строки — 79 символов.
  • Импорты корректно отсортированы, неиспользуемых импортов нет.
  • Отступы делаются в 4 пробела.
  • Переносы строк выполнены с правильными отступами.
  • Обратные слеши для переносов не используются.
  • Консистентность (одинаковые кавычки, одинаковые способы решения одинаковых задач).
  • Отсутствие закомментированного кода и стандартных комментариев-заглушек (# Create your views here. и т. п.).
  • Комментарии к функциям оформлены как docstring в соответствии с Docstring Conventions, то есть начинаются с заглавной буквы, заканчиваются точкой и содержат описание того, что делает функция.
  • Комментарии к коду краткие и информативные.
  • Длинные куски кода логически разделены пустыми строками, как абзацы в тексте.
  • Нет лишних операций.
  • Нет лишних else (если в if происходит return/raise); используется guard block.
  • В репозитории нет лишних файлов наподобие __pycache__ и .vscode, попадающих туда по невнимательности.
  • Исполняемый код в .py-файлах закрыт конструкцией if __name__ == "__main__":.
  • Для неизменяемых последовательностей данных предпочтительны кортежи, а не списки.
  • В f-строках используется только подстановка переменных, без логических и арифметических операций, вызовов функций и прочей динамики, мешающей читать шаблон.
  • Имена переменных, выбранные по смыслу, записаны по-английски; однобуквенных имён нет (кроме счётчиков в коротких циклах и общепринятых математических обозначений).
  • Функции и методы названы глаголами или глагольными фразами (get_data, compute_energy), а классы существительными (Particle, FieldSolver); функция-формула, возвращающая величину, допускает имя этой величины, как mean и exp в NumPy.
  • Магические числа вынесены в именованные константы.

Большинство перечисленных пунктов проверяются автоматически линтерами и форматтерами ruff, flake8, black, isort, работающими в редакторе. Если они настроены в редакторе и в CI, следить за этими правилами вручную почти не требуется. black и ruff format по умолчанию форматируют по 88 символов, а не по 79, поэтому длину необходимо задать явно в pyproject.toml ([tool.black] line-length = 79, [tool.ruff] line-length = 79), иначе форматтер будет конфликтовать с линтером на каждом коммите.

Задание. Применить этот список к чужому коду и оставить замечания: «Ревью чужого кода».