Сообщить об ошибке.

Комментарии в коде языка Python

Как комментировать код

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

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

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

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

При написании английского, следуйте Strunk и White.

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

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

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

Абзацы внутри комментария блока разделяются строкой, содержащей один #.

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

Используйте встроенные комментарии экономно.

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

Встроенные комментарии не нужны и фактически отвлекают, если они утверждают очевидное. Не делай этого:

x = x + 1 # увеличение x

Но иногда полезно:

x = x + 1 # Компенсация границы

Строки документации:

Условные обозначения для написания хорошей документации описаны в PEP 257.

  • Пишите строки документации для всех общедоступных модулей, функций, классов и методов. Строки документации не нужны для закрытых методов, но у вас должен быть комментарий, описывающий, что делает метод. Этот комментарий должен появиться после строки def.

  • В PEP 257 описаны хорошие соглашения о документах. Обратите внимание, что наиболее важно, что """ , заканчивающий многострочную строку документации, должно быть на отдельной строке:

    """Return a foobang
    
    Optional plotz says to frobnicate the bizbaz first.
    """
    
  • Для строк документации в одну строку, пожалуйста, сохраняйте закрывающий символ """ на этой же строке.