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

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

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

Ответы

Ответ 1

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

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

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

Смотрите: PEP 257

Ответ 2

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

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

Ответ 3

Используйте docstring:

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

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

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

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

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

Ответ 4

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

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

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

Ответ 5

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

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

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

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

Ответ 6

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

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

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

Ответ 7

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