The Google style guide zawiera doskonały przewodnik po stylach Pythona. Zawiera konwencje dla czytelnej składni docstring , która oferuje lepsze wskazówki niż PEP-257. Na przykład:

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

Chciałbym rozszerzyć to również o informacje typu w argumentach, jak opisano w tym Sphinx documentation tutorial . Na przykład:

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

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

Konwencje Docstring są wPEP-257 o wiele bardziej szczegółowe niż PEP-8.

Jednak docstringi wydają się być znacznie bardziej osobiste niż inne obszary kodu. Różne projekty będą miały swój własny standard.

Zazwyczaj zawsze dołączam docstringi, ponieważ mają one tendencję do pokazywania, jak korzystać z funkcji i co robi bardzo szybko.

Wolę zachować spójność, niezależnie od długości łańcucha. Lubię jak kodować wygląda gdy wcięcia i odstępy są spójne. Czyli używam:

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

Over:

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

I mają tendencję do pomijania komentowania pierwszej linijki w dłuższych docstringach:

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. 
    ...

Jak nikt o tym nie wspomniał: możesz również użyć numpy Docstring Standard. Jest szeroko stosowany w środowisku naukowym.

• specyfikacja formatu z numpy wraz z przykładem
• masz rozszerzenie sphinx do renderowania go: numpydoc
• i przykład jak pięknie może wyglądać renderowany docstring: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Napolean sphinx rozszerzenie do parse Google-style docstrings (zalecane w odpowiedzi na @Nathan) obsługuje również docstring w stylu Numpy i dokonuje krótkiego porównania obu.

I ostatni podstawowy przykład, aby dać pomysł, jak to wygląda:

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 jest oficjalnym standardem kodowania Pythona. Zawiera sekcję dotyczącą docstringów, która odnosi się do PEP-257 -- kompletnej specyfikacji docstringów.

It ' s Python; anything goes . Zastanów się, jak opublikować swoją dokumentację . Docstringi są niewidoczne z wyjątkiem czytników Twojego kodu źródłowego.

Ludzie naprawdę lubią przeglądać i przeszukiwać dokumentację w Internecie. Aby to osiągnąć, użyj narzędzia dokumentacji Sphinx . To de facto standard dokumentowania projektów Pythona. Produkt jest piękny-zobacz https://python-guide.readthedocs.org/en/latest /. Strona przeczytaj Docs będzie hostować Twoje dokumenty za darmo.

Proponuję użyć programu Vladimira Kelesheva pep257 Python, aby sprawdzić Twoje docstringi pod kątem PEP-257 i standardu Numpy Docstring do opisywania parametrów, zwrotów itp.

Pep257 zgłosi rozbieżność od standardu i nazywa się tak jak pylint i pep8.