Ich habe in Python einige verschiedene Arten des Schreibens von Docstrings gesehen. Gibt es einen offiziellen oder "vereinbarten" Stil?
python
coding-style
documentation
docstring
Noah McIlraith
quelle
quelle
epydoc
,doxygen
,sphinx
? Hat jemand irgendwelche Statistiken, wird einer von ihnen die anderen ersetzen, in solchen Fällen können zu viele Optionen schaden.def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Antworten:
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
Epytext
Format) verwendet, um Dokumentation zu generieren.Beispiel:
- 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:
- Google
Google hat ein eigenes Format , das häufig verwendet wird. Es kann auch von Sphinx interpretiert werden (dh mit dem Napoleon-Plugin ).
Beispiel:
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.
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
quelle
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:
Ich möchte dies erweitern, um auch Typinformationen in die Argumente aufzunehmen, wie in diesem Tutorial zur Sphinx-Dokumentation beschrieben . Zum Beispiel:
quelle
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:
Über:
Und neigen dazu, das Kommentieren der ersten Zeile in längeren Dokumentzeichenfolgen zu unterlassen:
Das heißt, ich finde Docstrings, die so anfangen, chaotisch.
quelle
"""Return the squared result"""
eher als"""Returns the squared result"""
. Obwohl ich persönlich schreibe, wie Tim hier ist, trotz der Aussagen des PEP.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:
quelle
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.
quelle
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.
quelle
ipython
es 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.help
Funktion 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).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.
quelle
pydocstyle --select=D4 tmp.py
Überprüfungen auf eine Reihe von Problemen mit dem Inhalt von Dokumentzeichenfolgen, einschließlich der Benennung von Abschnitten.