Я бачив декілька різних стилів написання доктрингів у Python, чи існує офіційний чи «узгоджений» стиль?

Формати

Документи Python можна записати у кількох форматах, як показали інші повідомлення. Однак формат docstring Sphinx за замовчуванням не згадувався і базується на reStructuredText (reST) . Ви можете отримати інформацію про основні формати в цій публікації блогу .

Зауважте, що відпочинок рекомендований PEP 287

Далі випливають основні використовувані формати для docstrings.

- Епітекст

Історично Javadoc як стиль переважав, так що було прийнято в якості основи для Epydoc (з викликуваним Epytextформаті) для створення документації.

Приклад:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- відпочинок

На сьогодні, мабуть, найбільш поширеним форматом є формат reStructuredText (reST), який використовується Sphinx для створення документації. Примітка: вона використовується за замовчуванням у JetBrains PyCharm (введіть потрійні лапки після визначення методу та натисніть клавішу Enter). Він також використовується за замовчуванням як вихідний формат у Pyment.

Приклад:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

У Google є власний формат, який часто використовується. Він також може бути інтерпретований Сфінксом (тобто, використовуючи плагін Наполеона ).

Приклад:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Ще більше прикладів

- Numpydoc

Зауважте, що Numpy рекомендують дотримуватися власного numpydoc, заснованого на форматі Google і використовуваному Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Перетворення / генерування

Можна використовувати такий інструмент, як Pyment, для автоматичного генерування документації до ще не задокументованого проекту Python, або для перетворення існуючих документів (може змішувати декілька форматів) з формату в інший.

Примітка. Приклади взяті з документації Pyment

Посібник зі стилів Google містить чудовий посібник зі стилів Python. Він включає умовні позначення для читаного синтаксису docstring, що пропонує кращі вказівки, ніж PEP-257. Наприклад:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Мені подобається розширити це, щоб також включити інформацію про типи в аргументи, як описано в цьому посібнику з документації щодо Сфінкса . Наприклад:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Докстринг-конвенції містяться в PEP-257 з набагато більш детальною інформацією, ніж PEP-8.

Однак, здається, документування набагато більш особисте, ніж інші області коду. У різних проектів буде свій стандарт.

Я прагну завжди включати docstrings, оскільки вони, як правило, демонструють, як використовувати функцію та що вона робить дуже швидко.

Я вважаю за краще тримати речі послідовними, незалежно від довжини струни. Мені подобається, як виглядає кодування, коли відступи та пробіли є послідовними. Це означає, що я використовую:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Понад:

def sq(n):
    """Returns the square of n."""
    return n * n

І схильні залишати коментарі до першого рядка в довших документах:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Значить, я знаходжу доктрини, які починаються таким чином, безладним.

def sq(n):
    """Return the squared result. 
    ...

Як про це ніхто не згадував: ви також можете скористатися Numpy Docstring Standard . Він широко використовується в науковому співтоваристві.

• Специфікація формату від Numpy разом з прикладом
• У вас є розширення сфінкса, щоб відтворити його: numpydoc
• І приклад того, як красиво може виглядати викладена докстрина: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Наполеївське розширення сфінкса для розбору документів у стилі Google (рекомендується у відповіді @Nathan) також підтримує докстринг у стилі Numpy і дає коротке порівняння обох.

І останній основний приклад, щоб дати уявлення про те, як це виглядає:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 є офіційним стандартом кодування python. Він містить розділ про docstrings, в якому йдеться про PEP-257 - повна специфікація для docstrings.

Це Python; все йде . Розглянемо, як опублікувати свою документацію . Документи невидимі, крім читачів вашого вихідного коду.

Люди дуже люблять переглядати та шукати документацію в Інтернеті. Для цього скористайтеся інструментом документації Sphinx . Це фактичний стандарт для документування проектів Python. Продукт прекрасний - подивіться на https://python-guide.readthedocs.org/en/latest/ . Веб-сайт « Прочитайте документи » розмістить ваші документи безкоштовно.

Я пропоную використовувати Володимир Keleshev в pep257 програму Python , щоб перевірити рядки документації в відношенні PEP-257 і Numpy рядки документації стандарту для опису параметрів, повертається, і т.д.

pep257 повідомить про розбіжність, який ви робите від стандарту, і називається як pylint та pep8.