PEP 8, Comments

Изучаем PEP 8 по частям. Часть 5, Comments.

Тут говорится о том, что:

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

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

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

Следует ставить два пробела после завершающей фразу точки.

Когда пишете на английском языке, следуйте правилам языка (The Elements of Style, Fourth Edition by William Strunk Jr., E. B. White).

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

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

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

Пореже используйте инлайн комментарии.

Инлайновый комментарий это коммент в той же строке, что и выражение. Комментарий отделяется от выражения двумя пробелами минимум и символом # с последующим пробелом.

Инлайновые комментарии часто не нужны и даже отвлекающи, когда декларируют очевидное. Но иногда они полезны.

x = x + 1                 # Compensate for border

Соглашение по написанию хороших докстрингов увековечены в PEP 257.

* Записывайте докстринги для всех публичных модулей, функций, классов и методов. Докстринги не обязательны для непубличных методов, но следует иметь комментарии, описывающие суть метода. Такой комментарий должен быть на строке следующей за «def ...».

* Закрывающие докстринги кавычки «”””» для многостроковых докстрингов, должны быть на отдельной строке.

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

http://legacy.python.org/dev/peps/pep-0008/

http://docs.python-guide.org/en/latest/writing/style/

Без комментариев. Хотя, про два пробела между фразами я как-то не очень понимаю. Нафейхоа? А так, все настолько очевидно, что комментариев не требует :)

original post http://vasnake.blogspot.com/2014/09/pep-8-comments.html