Комментарии в Python

Какие бывают

Обычные комментарии

Комментарии – способ прокомментировать код на ходу, на той же строке. Вот пример кода. Здесь, “Получил пользователя” – это комментарий.

user = get_user_by_id(...)  # Получил пользователя

Такие комментарии начинаются с символа #. Можно добавить комментарий на отдельной строке:

# Получил пользователя
user = get_user_by_id(...)

Комментарии ничего не делают, это просто заметки, которые можно оставлять прямо внутри программы.

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

# Получил пользователя
# user = get_user_by_id(...)

Докстринги

Докстринг – строковая переменная, которая идёт сразу за объявлением функции, класса, метода или модуля. Она нужна для документирования всей функции: описания входящих параметров, результата, логики, крайних случаев. Заключается в тройные двойные кавычки. Вот так:

def tensorsolve(a, b, axes=None):
    """
    Solve the tensor equation ``a x = b`` for x.
    It is assumed that all indices of `x` are summed over in the product,
    together with the rightmost indices of `a`, as is done in, for example,
    ``tensordot(a, x, axes=len(b.shape))``.
    """

В серьёзных проектах из них часто генерируется документация, поэтому они могут быть большими, по несколько экранов. Это касается проектов, у которых есть документация для разработчиков: Django, numpy, sqlalchemy.

Если проект не подразумевает, что им будут пользоваться другие разработчики, такого быть не должно. Длинных докстрингов не должно быть в скрипте ресайза изображений, сайте блога или алгоритме обучения нейронной сети.

Прямо в докстрингах можно писать короткие тесты, их называют доктесты. Ни разу не видел, чтобы кто-то это использовал в боевом проекте.

Как не использовать

Дублировать информацию из кода

Самая частая ошибка, связанная с комментариями: дублирование информации. В таком случае комментарий не несёт дополнительной информации, а просто переводит соседний код с Питона на русский/английский. Пример:

# загружаем данные из файла data.json
with open('users.json', 'r') as handler:
    data = json.load(handler)

Вот как можно исправить:

with open('users.json', 'r') as handler:
    data = json.load(handler)

А так – ещё лучше:

data = load_all_users_from_file()

Не поддерживать комментарии

Другая частая ошибка: не менять комментарии при изменении кода. В примере выше мы загружали данные из файла. Через месяц взялись за голову и поселили данные в базе данных. Код стал таким:

# загружаем данные из файла data.json
data = db_session.query(User).all()

Данные из файла? WAT?

Думать, что все поймут

Когда программист пишет кусок кода, он глубоко в него погружён: держит в голове все детали, связи и особые случаи. В таком состоянии всё поведение кажется понятным, поэтому разработчик может оставить комментарий самому себе. Проблема в том, что когда он переключится на другую задачу и забудет про детали, комментарий может взорвать мозг:

inv(strain_tensor) - rigidity.T  # правый случай

Правый, правда? Ну, теперь всё понятно.

Шутить

Шутки к неидеальному коду смотрятся неуместно. Представь, как чувствует себя разработчик, копающийся в чужом коде три часа и находящий новый модуль с заглавным комментарием оставь надежду, всяк сюда входящий. Не будь автором этого комментария. Лучше наведи порядок в своём коде.

Как использовать

Вот хорошие причины использовать комментарии:

• объяснить неочевидное поведение: бывает, что нужно объяснить какой-нибудь подводный камень куска кода или объяснить поведение в особом случае; использовать только если ту же информацию в коде поселить нельзя или очень сложно;
• оставить напоминание себе или коллеге: речь про комментарии вроде TODO: кешировать ответ ручки или FIXME: учитывать часовой пояс.

Прежде чем написать комментарий, попробуй поселить его в коде, указав параметр или дав подходящее название переменной.

Что изучать

• Доклад Григория Петрова про комментирование исходников. Обязателен к просмотру.
• PEP 257. ПЕП про докстринги.
• doctest. Документация к модулю про доктесты.
• What is the best comment in source code you have ever encountered?. Шутить в коде не стоит, а вот посмеяться с чужих шуток можно. Это ж не нам поддерживать.