Was ist das Standardformat für Python-Dokumentzeichenfolgen? [geschlossen]

888

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

Noah McIlraith
quelle
6
python.org/dev/peps/pep-0008 Es gibt einen ganzen Abschnitt über Dokumentationszeichenfolgen
Mechanical_Meat
30
Ich denke , dass diese Frage nicht klar genug war , weil PEP-257 und PEP-8 sind die nur die Basis für Docstrings Gründung, aber wie wäre es epydoc, doxygen, sphinx? Hat jemand irgendwelche Statistiken, wird einer von ihnen die anderen ersetzen, in solchen Fällen können zu viele Optionen schaden.
Sorin
1
@sorin, ich würde auch gerne wissen, welches Markup, wenn überhaupt, am häufigsten ist. Aber ich denke, die Antwort ist, dass keiner von ihnen wirklich so häufig vorkommt: Die Leute schauen sich die Python-Quelle lieber direkt an, als sie in HTML umzuwandeln. Daher ist es am nützlichsten, nur konsistent zu sein, aber auf eine Weise, die für die menschliche Lesbarkeit optimiert ist, und ohne explizites Markup.
Poolie
3
PyCharm wird auf ziemlich interessante Weise automatisch vervollständigt, was meiner Meinung nach eine nette Implementierung der Anweisungen ist, die zum Ausführen erforderlich sind:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla
1
Welche dieser Antworten funktioniert standardmäßig mit dem VS Code-Dokumentationsparser?
William Entriken

Antworten:

1019

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

daouzli
quelle
10
Ich könnte hinzufügen, dass reST in JetBrains PyCharm standardmäßig verwendet wird. Geben Sie einfach dreifache Anführungszeichen ein, nachdem Sie Ihre Methode definiert haben, und drücken Sie die Eingabetaste. jetbrains.com/pycharm/help/creating-documentation-comments.html
Felipe Almeida
12
Die umfassendste Antwort beinhaltet einen Sinn für Geschichte und aktuelle Best Practices. Jetzt brauchen wir nur noch ein Gefühl der Community-Bewegung in Richtung eines neuen "besten" Formats und einige zusätzliche Community-Anstrengungen, um Migrationswerkzeuge von allen anderen zu den neuen zu erstellen, damit wir tatsächlich Best Practices entwickeln können.
BobHy
2
yo @daouzli, der Link im Google-Stil ist 404. Ich glaube, dieser ist korrekt. Sie können auch ein Beispiel im Google-Stil für Sphinx hinzufügen . Tolle Antwort übrigens. EDIT: Ich habe deine Antwort selbst bearbeitet.
Voy
4
gute Antwort. Ich wage zu sagen, wo Sie das Standard-Docstring-Format in PyCharm (JetBrains) ändern können: Einstellungen -> Tools -> Integrierte Python-Tools -> Docstring-Format. Viel Glück!
Jackssn
4
Ich bin überrascht, dass niemand die erste Textzeile kommentiert hat: Derzeit ist sie streng genommen korrekt, aber ich denke, der bevorzugte Weg ist, sie direkt nach den dreifachen Anführungszeichen in die erste Zeile zu setzen. PEP 8 und PEP 257 tun dies in fast allen Beispielen. PEP 287 macht es auf Ihre Weise, aber meiner Erfahrung nach ist es nicht so üblich.
Lapinot
323

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
Nathan
quelle
37
Ich finde den "Signatur in Docstrings" -Stil schrecklich überflüssig und ausführlich. Für Python 3+ sind Funktionsanmerkungen eine viel sauberere Möglichkeit, dies zu tun. Noch schlimmer, wenn es pseudo-starke Typen verwendet: Python ist viel besser beim Entenschreiben.
Evpok
27
Ja, aber zumindest gibt es einen Hinweis darauf, welche Art von Ente erwartet wird, und die meisten Entwickler sind noch nicht auf Python 3
Anentropic
3
@ Evpok persönlich, ich mag keine Funktionsanmerkungen. Um Klassen in ihnen zu verwenden, müssen Sie möglicherweise unnötige Importe durchführen. Um Zeichenfolgen in ihnen zu verwenden, kann es sein, dass Ihnen der horizontale Raum sehr schnell ausgeht, um sie zu beschreiben. Bisher habe ich nicht den Sinn gesehen, sie für irgendetwas zu verwenden.
OdraEncoded
5
@Nathan, Googles Styleguide empfiehlt Kommentare, die eher beschreibend als deklarativ sind, z. B. "Ruft Zeilen von einer Bigtable ab" über "Ruft Zeilen von einer Bigtable ab". Wenn Sie also "Berechnen ..." in "Berechnen ..." ändern, wird Ihr Beispiel konsistenter mit dem Rest des Kommentars, dh "Rückgaben" und "Erhöhungen".
GWG
2
nit: Verwenden Sie nach dem Google-Stil eher eine beschreibende als eine zwingende Form, dh "Berechnet ..." und "Fügt hinzu ..."
sbeliakov
228

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. 
    ...
Tim McNamara
quelle
90
Beachten Sie, dass PEP-8 ausdrücklich besagt, dass die Dokumentzeichenfolgen als Befehle / Anweisungen und nicht als Beschreibungen geschrieben werden sollten, z. """Return the squared result"""eher als """Returns the squared result""". Obwohl ich persönlich schreibe, wie Tim hier ist, trotz der Aussagen des PEP.
Cam Jackson
63
Ich bin auch nicht mit diesem Rat einverstanden (unter Verwendung der Imperativform), weil er für etwas länger als einen Satz unangenehm klingt. Außerdem beschreiben Sie eine Funktion und sagen dem Leser nicht, was zu tun ist.
mk12
14
Hinweis: Die Spezifikation für vorschreibende und nicht beschreibende Dokumentzeichenfolgen wird tatsächlich in PEP-257 und nicht in PEP-8 angezeigt . Ich komme aus einer Java-Tradition, in der ich Funktionen beschrieb, aber ich begann schließlich, die Imperativform zu verwenden, als mein Programmierparadigma von objektorientiert zu prozedural wechselte. Und als ich anfing, Pycco zu verwenden, um eine Dokumentation im Stil einer literarischen Programmierung zu erstellen , wurde sehr deutlich, warum die Imperativform vorgeschlagen wurde. Sie sollten basierend auf Ihrem Paradigma wählen.
karan.dodia
26
Der Imperativ ist eine grammatikalische Stimmung . (Entschuldigung.)
Denis Drescher
5
@ Mk12 Git-Commit-Nachrichten sollten auch als Befehle anstelle von Beschreibungen geschrieben werden. Und sie " beschreiben " auch eine Codeänderung, "ohne dem Leser zu sagen, was zu tun ist". Ich denke, es ist nur eine Konvention, Beschreibungen als Befehle zu schreiben.
Stück
58

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

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
Joris
quelle
2
Das NumPy-Format IMHO benötigt zu viel vertikalen Platz, der auf Breitbildmonitoren knapp ist (außer Sie verwenden einen um 90 Grad gedrehten, aber ich denke, die meisten Leute tun dies nicht). Daher ist das IMHO-Google-Format eine gute Wahl in Bezug auf Lesbarkeit und Funktionen.
Semanino
3
Ich nehme an, es ist etwas subjektiv. Sobald Sie eine komplexere Dokumentzeichenfolge haben (mit verschiedenen Abschnitten, Beispielen usw., die unabhängig vom Format ohnehin viel vertikalen Platz beansprucht), finde ich das numpydoc-Format leichter zu lesen / besser strukturiert.
Joris
2
Persönlich bin ich der Meinung, dass ein so langer Dokumentstring besser in der Dokumentation und nicht im Quellcode zu finden ist, wenn er so lang ist, dass er die Lesbarkeit des Moduls beeinträchtigt.
Jonathan Hartley
12

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.

bstpierre
quelle
8
Die Erwähnung von PEP-257 im Zusammenhang mit "Wie soll ich Parameter, Rückgabewerte, ausgelöste Ausnahmen usw. ordnungsgemäß dokumentieren?" Ist ein WITZ - es sagt kein einziges Wort darüber aus (obwohl ein Codebeispiel einige zeigt). IMHO Google Format ist eine gute Wahl in Bezug auf Lesbarkeit und Funktionen.
Semanino
9

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.

Oberst Panik
quelle
22
Ich benutze ipythones routinemäßig , um eine Bibliothek zu testen, und es macht das Lesen von Dokumentzeichenfolgen kinderleicht - alles, was ich eingeben muss, ist, your_module.some_method_im_curious_about?und ich bekomme jeden schönen Ausdruck, einschließlich Dokumentzeichenfolge.
Thanatos
8
Die Benutzer einer Bibliothek oder einer API oder die ein Plugin schreiben , sehen sich wahrscheinlich den Code an und müssen ihn verstehen. Ich finde Kommentare in Python weitaus wichtiger als in Java oder C #, da Typen nicht deklariert sind. Es ist sehr hilfreich, wenn die Kommentare eine ungefähre Vorstellung davon geben, welche Arten von Enten übergeben und zurückgegeben werden. (Andernfalls müssen Sie tatsächlich den gesamten Code durchlaufen und feststellen, dass ein bestimmter Parameter ... hier iterierbar sein muss ... die Indizierung dort unterstützen ... die numerische Subtraktion am Ende unterstützen ... Aha! Es ist im Grunde eine int array. Ein Kommentar hätte geholfen!)
Jon Coombs
Ähm nein. Docstrings sind nicht unsichtbar und das ist ein bisschen der Punkt. Sie sehen die Dokumentzeichenfolge, wenn Sie die helpFunktion für die dokumentierte Funktion / Methode / Klasse ausführen (und dies auch dann, wenn Sie nur Zugriff auf das kompilierte Modul haben). Persönlich denke ich, dass man dies berücksichtigen sollte, wenn man die Docstring-Konvention wählt (dh, dass beabsichtigt ist, sie so zu lesen, wie sie ist).
Skyking
7

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.

Finn Årup Nielsen
quelle
Die Erwähnung von PEP-257 im Zusammenhang mit "Wie soll ich Parameter, Rückgabewerte, ausgelöste Ausnahmen usw. ordnungsgemäß dokumentieren?" Ist ein WITZ - es sagt kein einziges Wort darüber aus (obwohl ein Codebeispiel einige zeigt). Das NumPy-Format IMHO benötigt zu viel vertikalen Platz, der auf Breitbildmonitoren knapp ist (außer Sie verwenden einen um 90 Grad gedrehten, aber ich denke, die meisten Leute tun dies nicht). Daher ist das IMHO-Google-Format eine gute Wahl in Bezug auf Lesbarkeit und Funktionen.
Semanino
1
@Semanino Ich erwähne den Numpy Docstring Standard im Kontext des Programms pep257 - nicht PEP-257. Dieses Programm heißt jetzt pydocstyle. Mit pydocstyle können Sie einige Numpydoc-Überprüfungen durchführen, z. B. pydocstyle --select=D4 tmp.pyÜberprüfungen auf eine Reihe von Problemen mit dem Inhalt von Dokumentzeichenfolgen, einschließlich der Benennung von Abschnitten.
Finn Årup Nielsen