Який правильний спосіб коментувати функції в Python?

Чи існує загальноприйнятий спосіб коментувати функції в Python? Чи прийнятне наступне?

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

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

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

Це три подвійні лапки, щоб відкрити коментар та ще три подвійні лапки, щоб закінчити його. Ви також можете використовувати будь-яку дійсну рядок Python. Він не повинен бути багаторядковим, а подвійні лапки можна замінити одинарними.

Див .: PEP 257

Використовуйте docstring, як уже писали інші.

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

Використовуйте docstring :

Строковий літерал, який виникає як перший вираз у визначенні модуля, функції, класу чи методу. Така доктрина стає __doc__особливим атрибутом цього об’єкта.

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

Строкові літерали, які зустрічаються в іншому місці в коді Python, також можуть виступати в якості документації. Вони не розпізнаються компілятором байт-кодів Python і не є доступними як атрибути об'єкта виконання (тобто не призначені __doc__), однак два типи додаткових доктрин можуть бути вилучені програмними засобами:

1. Літеральні рядки, що виникають одразу після простого призначення на верхньому рівні модуля, класу чи __init__методу, називаються "атрибути".
2. Літеральні рядки, що виникають одразу після іншого docstring, називаються "додатковими документами".

Будь ласка, дивіться 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 під час піпарсингу) та використовуйте розпізнаваний синтаксисом розмітки. Запускайте цей інструмент часто, займаючись розробкою, щоб виявити дірки в документації. Насправді ви навіть можете отримати користь від написання документів для членів класу перед реалізацією класу.

Використовуйте docstrings .

Це вбудована запропонована конвенція в PyCharm для коментарів щодо опису функції:

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

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

Хоча я згоден, що це має бути не коментарем, а докстрингом, як підказує більшість (усіх?) Відповідей, я хочу додати numpydoc (посібник зі стилю docstring ) .

Якщо ви робите це так, ви можете (1) автоматично генерувати документацію та (2) люди розпізнавати це та мати легший час для читання вашого коду.

Ви можете використовувати три лапки для цього.

Ви можете використовувати одинарні лапки:

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

Або подвійні цитати:

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