Комментарии – способ прокомментировать код на ходу, на той же строке.

price = Column(BigInteger) # рубли * 100

Докстринг – строковая переменная, которая идёт сразу за объявлением функции, класса, метода или модуля.

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

Заключается в тройные двойные кавычки. Вот так:

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: учитывать часовой пояс`.

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

- [Доклад Григория Петрова про комментирование исходников](https://www.youtube.com/watch?v=-SRUctRR_4s). Обязателен к просмотру.

- [PEP 257](https://www.python.org/dev/peps/pep-0257/). ПЕП про докстринги.

- [doctest](https://docs.python.org/3.5/library/doctest.html). Документация к модулю про доктесты.

- [What is the best comment in source code you have ever encountered?](http://stackoverflow.com/questions/184618/). Шутить в коде не стоит, а вот посмеяться с чужих шуток можно. Это ж не нам поддерживать.