Комментарии: когда нужны, когда лишние

Комментарии — инструмент, а не обязанность. Хороший комментарий экономит время, плохой — только шумит.

Хороший комментарий объясняет «почему»

Код показывает, ЧТО он делает. Комментарий полезен, когда объясняет, ПОЧЕМУ выбрано именно такое решение, или предупреждает о неочевидном подводном камне.

Например: «# округляем вверх, иначе теряем последнюю страницу».

Лишние комментарии

Комментарий, повторяющий код, бесполезен: «i = i + 1 # увеличиваем i на 1». Он только отвлекает.

Если хочется комментарием пояснить запутанный кусок — часто лучше переписать сам код понятнее.

Docstring для функций

В Python у функций есть документирующая строка (docstring) — текст в тройных кавычках сразу после «def». В ней коротко описывают, что функция делает и что возвращает.

Docstring видят редакторы и функция help(), поэтому это удобнее обычного комментария для описания назначения.

Опасность устаревших комментариев

Если код изменили, а комментарий — нет, он начинает врать. Такой комментарий хуже, чем его отсутствие.

Правило простое: меняешь код — проверь и обнови комментарии рядом.

Частые вопросы

Сколько комментариев нужно? Ровно столько, чтобы понять неочевидное. Цель — понятный код, а не много текста.

Чем docstring отличается от комментария? Docstring — часть объекта и доступна в runtime через help(); обычный комментарий — только для чтения.