Ich habe in Python einige verschiedene Arten des Schreibens von Docstrings gesehen. Gibt es einen offiziellen oder "vereinbarten" Stil?

Formate

Python-Dokumentzeichenfolgen können in verschiedenen Formaten geschrieben werden, wie in den anderen Beiträgen gezeigt. Das Standard-Sphinx-Dokumentzeichenfolgenformat wurde jedoch nicht erwähnt und basiert auf reStructuredText (reST) . Informationen zu den Hauptformaten finden Sie in diesem Blogbeitrag .

Beachten Sie, dass der reST vom PEP 287 empfohlen wird

Es folgen die wichtigsten verwendeten Formate für Dokumentzeichenfolgen.

- Epytext

Historisch gesehen war ein Javadoc- ähnlicher Stil vorherrschend, daher wurde er als Basis für Epydoc (mit dem aufgerufenen EpytextFormat) verwendet, um Dokumentation zu generieren.

Beispiel:

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

- sich ausruhen

Heutzutage ist das wahrscheinlich am weitesten verbreitete Format das reStructuredText (reST) -Format, das von Sphinx zum Generieren von Dokumentation verwendet wird. Hinweis: In JetBrains PyCharm wird es standardmäßig verwendet (geben Sie nach dem Definieren einer Methode dreifache Anführungszeichen ein und drücken Sie die Eingabetaste). Es wird auch standardmäßig als Ausgabeformat in Pyment verwendet.

Beispiel:

"""
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 hat ein eigenes Format , das häufig verwendet wird. Es kann auch von Sphinx interpretiert werden (dh mit dem Napoleon-Plugin ).

Beispiel:

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

Noch mehr Beispiele

- Numpydoc

Beachten Sie, dass Numpy empfiehlt, einem eigenen numpydoc zu folgen, das auf dem Google-Format basiert und von Sphinx verwendet werden kann.

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

Konvertieren / Generieren

Mit einem Tool wie Pyment können Sie automatisch Dokumentzeichenfolgen für ein noch nicht dokumentiertes Python-Projekt generieren oder vorhandene Dokumentzeichenfolgen (die mehrere Formate mischen können) von einem Format in ein anderes konvertieren.

Hinweis: Die Beispiele stammen aus der Pyment-Dokumentation

Der Google Style Guide enthält einen ausgezeichneten Python Style Guide. Es enthält Konventionen für lesbare Docstring-Syntax , die eine bessere Anleitung als PEP-257 bieten. Zum Beispiel:

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

Ich möchte dies erweitern, um auch Typinformationen in die Argumente aufzunehmen, wie in diesem Tutorial zur Sphinx-Dokumentation beschrieben . Zum Beispiel:

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

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

Docstring-Konventionen sind in PEP-257 viel detaillierter als in PEP-8.

Docstrings scheinen jedoch weitaus persönlicher zu sein als andere Codebereiche. Verschiedene Projekte haben ihren eigenen Standard.

Ich neige dazu, immer Docstrings einzuschließen, weil sie zeigen, wie man die Funktion benutzt und was sie sehr schnell macht.

Ich ziehe es vor, die Dinge konsistent zu halten, unabhängig von der Länge der Saite. Mir gefällt, wie Code aussieht, wenn Einrückung und Abstand konsistent sind. Das heißt, ich benutze:

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

Über:

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

Und neigen dazu, das Kommentieren der ersten Zeile in längeren Dokumentzeichenfolgen zu unterlassen:

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

Das heißt, ich finde Docstrings, die so anfangen, chaotisch.

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

Wie es anscheinend niemand erwähnte: Sie können auch den Numpy Docstring Standard verwenden . Es ist in der wissenschaftlichen Gemeinschaft weit verbreitet.

• Die Angabe des Formats von numpy zusammen mit einem Beispiel
• Sie haben eine Sphinx-Erweiterung, um es zu rendern: numpydoc
• Und ein Beispiel dafür, wie schön ein gerenderter Dokumentstring aussehen kann: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Die napoleonische Sphinx-Erweiterung zum Parsen von Docstrings im Google-Stil (empfohlen in der Antwort von @Nathan) unterstützt auch Docstring im Numpy-Stil und bietet einen kurzen Vergleich beider.

Und als letztes ein einfaches Beispiel, um eine Vorstellung davon zu geben, wie es aussieht:

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 ist der offizielle Python-Codierungsstandard. Es enthält einen Abschnitt über Dokumentzeichenfolgen, der sich auf PEP-257 bezieht - eine vollständige Spezifikation für Dokumentzeichenfolgen.

Es ist Python; alles geht . Überlegen Sie, wie Sie Ihre Dokumentation veröffentlichen . Docstrings sind außer für Leser Ihres Quellcodes unsichtbar.

Die Leute durchsuchen und durchsuchen gerne Dokumentationen im Web. Verwenden Sie dazu das Dokumentationstool Sphinx . Dies ist der De-facto-Standard für die Dokumentation von Python-Projekten. Das Produkt ist wunderschön - werfen Sie einen Blick auf https://python-guide.readthedocs.org/en/latest/ . Auf der Website Read the Docs werden Ihre Dokumente kostenlos gehostet.

Ich schlage vor, das pep257 Python-Programm von Vladimir Keleshev zu verwenden , um Ihre Docstrings mit PEP-257 und dem Numpy Docstring Standard zu vergleichen und Parameter, Rückgaben usw. zu beschreiben.

pep257 meldet Abweichungen vom Standard und wird wie pylint und pep8 bezeichnet.