Как правильно комментировать функции в Python?

Question

Есть ли общепринятый способ сделать это? Это приемлемо:

#########################################################
# Create a new user
#########################################################
def add(self):

Answer 1

Правильный способ сделать это - предоставить строку документации. Таким образом, help(add) также выложит ваш комментарий.

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

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

См .: PEP 257

Answer 2

Используйте строку документации, как уже написали другие.

Вы даже можете пойти еще дальше и добавить doctest к вашей строке документации, что сделает автоматическое тестирование ваших функций простым.

Answer 3

Использовать строку документации :

строковый литерал, который встречается как первый оператор в определении модуля, функции, класса или метода. Такая строка документации становится __doc__ специальным атрибутом этого объекта.

У всех модулей обычно должны быть строки документов, и все функции и классы, экспортируемые модулем, также должны иметь строки документов. Публичные методы (включая конструктор __init__) также должны иметь строки документации. Пакет может быть задокументирован в строке документации модуля __init__.py в каталоге пакета.

Строковые литералы, встречающиеся в других местах кода Python, также могут выступать в качестве документации. Они не распознаются компилятором байт-кода Python и недоступны в качестве атрибутов объекта среды выполнения (т. Е. Не назначены __doc__), но программные инструменты могут извлекать два типа дополнительных строк документации:

1. Строковые литералы, встречающиеся сразу после простого присваивания на верхнем уровне модуля, класса или __init__ метода, называются «строки документации атрибута».
2. Строковые литералы, встречающиеся сразу после другой строки документа, называются «дополнительными строками документа».

Пожалуйста, смотрите PEP 258 , "Спецификация проекта Docutils" [2] , для подробного описания атрибута и дополнительных строк документации ...

Answer 4

О, мальчик! Рассмотрим открытую банку с червями:)

Принципы хорошего комментирования довольно субъективны, но вот некоторые рекомендации:

• Комментарии к функциям должны описывать намерение функции, а не реализацию
• Укажите любые предположения, которые ваша функция делает в отношении состояния системы. Если он использует какие-либо глобальные переменные (tsk, tsk), перечислите их.
• Остерегайтесь чрезмерного ASCII Art. Может показаться, что наличие длинных цепочек хэшей облегчает чтение комментариев, но при изменении комментариев они могут раздражать.
• Воспользуйтесь преимуществами языковых возможностей, которые предоставляют «автоматическую документацию», то есть строки документации в Python, POD в Perl, Javadoc в Java

Answer 5

Прочтите об использовании строк документации в вашем коде Python.

В соответствии с соглашениями Python Docstring:

Строка документации для функции или метода должна обобщать их поведение и документировать свои аргументы, возвращаемые значения, побочные эффекты, возникающие исключения и ограничения на то, когда он может быть вызван (все, если применимо). Необязательные аргументы должны быть указаны. Должно быть задокументировано, являются ли ключевые аргументы частью интерфейса.

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

Answer 6

Я бы пошел на практику документирования, которая интегрируется с инструментом документации, таким как Sphinx .

Первый шаг - использовать docstring:

def add(self):
 """ Method which adds stuff
 """

Answer 7

Я бы пошел дальше, чем просто сказать "использовать строку документации". Выберите инструмент создания документации, такой как pydoc или epydoc (я использую epydoc в pyparsing), и используйте синтаксис разметки, распознаваемый этим инструментом. Во время разработки часто запускайте этот инструмент, чтобы выявить пробелы в документации. Фактически, вы могли бы даже выиграть от написания строк документации для членов класса до реализации класса.

Answer 8

Хотя я согласен с тем, что это должен быть не комментарий, а строка документа, как предлагает большинство (все?) Ответов, я хочу добавить numpydoc (руководство по стилю документации) .

Если вы делаете это таким образом, вы можете (1) автоматически создавать документацию (2) люди распознают это и им легче читать ваш код.