Официальные стили Python перечислены в PEP-8 .

Руководство по стилю в стиле 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

Мне нравится расширять его, чтобы также включать информацию о типе в аргументы, как описано в этом учебнике документации Sphinx . Например:

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

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

PEP-8 является официальным стандартом кодирования питона. Он содержит раздел о docstrings, который ссылается на PEP-257 - полную спецификацию для docstrings.

Это Python; все идет . Подумайте, как опубликовать свою документацию . Докстоны невидимы, за исключением читателей вашего исходного кода.

Люди действительно любят просматривать и искать документацию в Интернете. Для этого используйте инструмент документации Sphinx . Это де-факто стандарт для документирования проектов Python. Продукт прекрасен - посмотрите на https://python-guide.readthedocs.org/en/latest/ . На веб-сайте «Чтение документов» будут размещены ваши документы бесплатно.

Я предлагаю использовать программу Python Владимира Келешева pep257 Python для проверки ваших docstrings против PEP-257 и Nump Docstring Standard для описания параметров, возвращает и т. д.

pep257 сообщит о дивергенции, которую вы делаете из стандарта, и называется как pylint и pep8.

В качестве apparanty никто не упоминал об этом: вы также можете использовать стандарт Nump Docstring.

• Спецификация формата из numpy вместе с примером
• ] У вас есть расширение sphinx для его рендеринга: numpydoc
• И пример того, как красиво выглядит отображаемая docstring: http://docs.scipy.org /doc/numpy/reference/generated/numpy.mean.html

Наполеанское расширение сфинкса для разбора докстронгов в стиле Google (рекомендуется в ответ @Nathan) также поддерживает Docstring в стиле 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

Соглашения docstring находятся в PEP-257 с гораздо большей детализацией, чем PEP-8.

Однако докстры, по-видимому, гораздо более личны, чем другие области кода. У разных проектов будет свой собственный стандарт.

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

Я предпочитаю сохранять согласованность, независимо от длины строки. Мне нравится, как выглядит код, когда отступы и интервалы согласованы. Это означает, что я использую:

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

Over:

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

И, как правило, не комментирует первую строку в более длинных docstrings:

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

Значение Я нахожу docstrings, которые начинаются так, как будто это беспорядочно.

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