Требования к программам
Для того, чтобы комментарии на русском языке были точно читаемыми, добавьте в начало кода следующую строку:
# -*- coding: utf-8 -*-
Правила
Правила и рекомендации нужно применять в порядке следования: чем раньше идёт правило, тем оно важнее- Бритва Оккама
- Здравый смысл при именовании сущностей: имя должны быть говорящими, но не слишком длинными
- PEP20. The Zen of Python (Дзен Питона). Если Вы программируете как-то иначе, то скорее всего Вы программируете не на Python. Оригинал и перевод.
- PEP8. Style Guide for Python Code (Руководство по стилю кода на Python). Ejudge автоматически проверяет сдаваемые код на соответствие с этим руководством. Для автоматической проверки можно использовать утилиту
pycodestyle
(иногда она распространяется под старым именемpep8
). Ejudge запускает её так:pycodestyle --max-line-length=102 --show-source --show-pep8 --ignore=W503 --ignore=W292
Оригинал и неплохой перевод. Во многие IDE встроены средства автоматического форматирования. Например, плагин для vim. - Docstrings и аннотации должны присутствовать. Если хочется разобраться, то имеет смысл почитать PEP в следующем порядке: 483, 3107, 484, 526. Аннотации можно проверять статическим анализатором, например mypy. Ejudge запускает
mypy
так:mypy --warn-unused-configs --disallow-subclassing-any --disallow-any-generics --disallow-untyped-calls --disallow-untyped-defs\ --disallow-incomplete-defs --check-untyped-defs --disallow-untyped-decorators --no-implicit-optional --warn-redundant-casts --warn-unused-ignores\ --no-implicit-reexport --warn-no-return --warn-unreachable --allow-redefinition\ --no-incremental --show-error-context --show-column-numbers --show-error-codes
При этом для самостоятельной проверки рекомендуется использовать утилиту
dmypy
(входит в стандартную поставку) и не использовать ключ --no-incremental
- Для общего развития правила оформления программ в соседних классах эти и эти.
- Правила написания кода проекта GNU. Большой сложный документ, охватывающий почти все возможные и невозможные случаи. Основной минус: они написаны для C/C++, поэтому некоторые технические детали к нам не относятся. Стоит обратить внимание на разделы 4.2, 4.4, 4.11, 4.12, 5.1, 5.2, 5.4, 6.2.
Так же советую обратить внимание на следующие утилиты: pdb, pylint, flake.
Немного про аннотации
Для написания аннотаций бывает полезен модульtyping
. Он может много чего, но отдельно стоит выделить:1. Типы для контейнеров. Например правильное определение функции поиска среднего в списке целых числе такое:
from typing import List def average(A: List[int]) -> float: """Return average value of A.""" return sum(A) / len(A)
2. Тип
Any
. Им не стоит злоупотреблять, но многие вещи без него сделать нельзя. Например функция сортировки определяется как-то так:from typing import List, Any def Sort(A: List[Any]) -> List[Any]: """Return sorted version of A.""" return sorted(A)
3. Иногда нужны аннотации к данным не только в объявлениях функций. Например, считывание 100 построчно введённых целых чисел стоит оформлять так:
from typing import List arr = [] # type: List[int] for i in range(100): arr.append(int(input()))