Правила Написания Программ

Требования к программам


Для того, чтобы комментарии на русском языке были точно читаемыми, добавьте в начало кода следующую строку:

# -*- coding: utf-8 -*-


Правила

Правила и рекомендации нужно применять в порядке следования: чем раньше идёт правило, тем оно важнее

  1. Бритва Оккама
  2. Здравый смысл при именовании сущностей: имя должны быть говорящими, но не слишком длинными
  3. PEP20. The Zen of Python (Дзен Питона). Если Вы программируете как-то иначе, то скорее всего Вы программируете не на Python. Оригинал и перевод.
  4. PEP8. Style Guide for Python Code (Руководство по стилю кода на Python). Ejudge автоматически проверяет сдаваемые код на соответствие с этим руководством. Для автоматической проверки можно использовать утилиту pycodestyle (иногда она распространяется под старым именем pep8). Ejudge запускает её так:
    pycodestyle.py --show-source  --show-pep8 --select=E,W
    Оригинал и неплохой перевод.
  5. Docstrings и аннотации должны присутствовать. Аннотации можно проверять статическим анализатором, например mypy.
  6. Для общего развития правила оформления программ в соседних классах эти и эти.
  7. Правила написания кода проекта GNU. Большой сложный документ, охватывающий почти все возможные и невозможные случаи. Основной минус: они написаны для C/C++, поэтому некоторые технические детали к нам не относятся. Стоит обратить внимание на разделы 4.2, 4.4, 4.11, 4.12, 5.1, 5.2, 5.4, 6.2.

Так же советую обратить внимание на следующие утилиты: pdb, pylint, flake.

Немного про аннотации

Для написания аннотаций бывает полезен модуль typing. Он может много чего, но отдельно стоит выделить:
1. Типы для контейнеров. Например правильное определение функции поиска среднего в списке целых числе такое:

def average(A: List[int]) -> float:
    """Return average value of A."""
    return sum(A) / len(A)

1. Тип Any. Им не стоит злоупотреблять, но многие вещи без него сделать нельзя. Например функция сортировки определяется как-то так:
def Sort(A: List[Any]) -> List[Any]:
    """Return sorted version of A."""
    return sorted(A)

%%