Готовый перевод Style Guide for Python Code: Comments

Комментарии

Комментарии противоречащие коду хуже, чем их отсутствие.

Всегда ставьте приоритет на то, чтобы комментарии были актуальными изменившемуся коду.

Комментарии должны быть закончеными предложениями.

Если комментарий - фраза или предложение, то первое слово должно начинаться с заглавной буквы, если только то не идентификатор, который начинается с буквы нижнего регистра(никогда не меняйте регистр идентификаторов!).

Если комментарий короткий, то точка на конце может быть опущена.

Блоковые комментарии обычно насчитывают один или более параграф состоящих из законченных предложений, каждой из которых заканчивается точкой.

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

При написании комментариев соблюдайте правописание и стилистику языка.

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

Блоки комментариев.

Блоковые комментарии обычно добавляются к некоторой части(или всему) коду, который их сопровождает и выравнены на тот же уровень, что и код программы.

Каждая стока блоковых комментариев начинается с # и заканчивается одним пробелом (до тех пор пока нет текста с отступами внутри комментария).

Параграфы внутри блокового комментария разделены строкой содержащей один символ #.

Внутристрочные комментарии

Поменьше используйте внутристрочные комментарии.

Строчный комментарий - это комментарий, находящийся на одной строке с выражением.

Внутристрочные комментарии следует отделять как минимум двумя пробелами от выражения.
Им следует начинаться с одного символа # и одного пробела.

Внутристрочные комментарии необязательны и фактически отталкивают, если они обьясняют очевидное.

Не пишите так:

x = x + 1 # Инкремент x

Но иногда, бывает полезно написать:

x = x + 1 # компенсатор для границы

Переведено на Нотабеноиде
http://notabenoid.org/book/1336/5352

Переводчики: wuffur, svartalf, Gukoff