Style Guide for Python Code: Comments

Комментарии

svartalf 17.02.09 в 14:38

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

wuffur 23.03.09 в 10:30

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

wuffur 23.03.09 в 10:36

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

wuffur 23.03.09 в 10:37

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

wuffur 23.03.09 в 10:41

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

wuffur 23.03.09 в 10:44

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

wuffur 24.03.09 в 07:21

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

wuffur 24.03.09 в 07:22

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

Gukoff 05.02.15 в 15:08

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

wuffur 24.03.09 в 07:27

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

wuffur 24.03.09 в 07:28

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

wuffur 24.03.09 в 07:30

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

wuffur 24.03.09 в 07:36

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

wuffur 24.03.09 в 07:37

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

wuffur 24.03.09 в 07:37

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

wuffur 24.03.09 в 07:38

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

svartalf 17.02.09 в 14:39

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

wuffur 24.03.09 в 07:42

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

wuffur 24.03.09 в 07:45

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

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

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

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

wuffur 24.03.09 в 07:47