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


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

#########################################################
# Create a new user
#########################################################
def add(self):
8   126   2010-03-01 19:21:13

8 ответов:

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

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

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

посмотреть: PEP 257

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

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

использовать docstring:

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

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

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

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

см. PEP 258, "Docutils Design Specification"[2], для детального описания атрибута и дополнительных docstrings...

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

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

  • комментарии функций должны описывать намерение функции, а не выполнение
  • изложите любые предположения, которые ваша функция делает в отношении состояния системы. Если он использует какие-либо глобальные переменные (ТСС), перечислите их.
  • следите за чрезмерным ASCII Art. Давно строки хэшей могут показаться, чтобы сделать комментарии легче читать, но они могут быть раздражающими, чтобы иметь дело с тем, когда комментарии меняются
  • воспользуйтесь языковыми функциями, которые обеспечивают "автоматическую документацию", т. е. docstrings в Python, POD в Perl, Javadoc в Java

читать об использовании docstrings в вашем коде python.

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

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

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

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

первым шагом является использование docstring:

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

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

хотя я согласен, что это должен быть не комментарий, а строка документа, как большинство (все?) ответы подсказывают, я хочу добавить numpydoc (руководство по стилю docstring): https://github.com/numpy/numpy/blob/254c50af3a52c8b1444e46857e9ec59fcb212a41/doc/HOWTO_DOCUMENT.rst.txt

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