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

Есть ли общепринятый способ комментировать функции в Python? Является ли следующее приемлемым?

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

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

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

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

Смотри: PEP 257

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

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

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

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

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

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

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

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

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

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

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

Согласно соглашениям документации Python :

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

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

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

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

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

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

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

Это встроенное предложенное соглашение в PyCharm для комментариев описания функций:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

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

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

Вы можете использовать три цитаты, чтобы сделать это.

Вы можете использовать одинарные кавычки:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

Или двойные кавычки:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """