So dokumentieren Sie Python-Code mit Docstrings

Ohne ordnungsgemäße Dokumentation kann es schwierig sein, Ihren Code zu verstehen, zu warten und zu debuggen. In Python können Sie Docstrings verwenden, um prägnante Beschreibungen und Beispiele für die Funktionsweise des Codes bereitzustellen.

Was sind Docstrings?

Docstrings sind Zeichenfolgen, die Sie Ihrem Python-Code hinzufügen können, um zu erklären, was er tut und wie er verwendet wird. Das Stück Code kann a sein Python-Funktion, ein Modul oder eine Klasse.

Docstrings sehen sehr nach Standard-Python-Kommentaren aus, weisen jedoch einige Unterschiede auf. Python-Kommentare bieten Entwicklern zusätzliche Informationen über das Innenleben des Codes, z. B. Implementierungsdetails oder Vorbehalte, die beim Erweitern des Codes zu beachten sind.

Auf der anderen Seite stellen Docstrings hauptsächlich Informationen für Benutzer des Codes bereit, die möglicherweise nicht unbedingt die Implementierungsdetails kennen müssen, aber verstehen müssen, was er tut und wie er verwendet wird.

Wie man Docstrings schreibt

Normalerweise fügen Sie Dokumentzeichenfolgen am Anfang des Codeblocks ein, den Sie dokumentieren möchten. Sie müssen sie in dreifache Anführungszeichen setzen (). Sie können einzeilige oder mehrzeilige Dokumentzeichenfolgen schreiben.

Einzeilige Docstrings eignen sich für einfachen Code, der nicht viel Dokumentation erfordert.

Unten ist ein Beispiel für eine Funktion namens multiplizieren. Der Docstring erklärt, dass die multiply-Funktion zwei Zahlen nimmt, sie multipliziert und das Ergebnis zurückgibt.

defmultiplizieren(a, b):
Multipliziert zwei Zahlen und gibt das Ergebnis zurück
zurückkehren a*b

Verwenden Sie mehrzeilige Dokumentzeichenfolgen für komplexeren Code, der eine ausführliche Dokumentation erfordert.

Betrachten Sie die folgende Autoklasse:

KlasseAuto:

 A KlassevertretenAAutoObjekt.
 Attribute:
 Kilometerstand (Float): Der aktuelle Kilometerstand des Autos.
 Methoden:
 fahren (Meilen): Fährt das Auto für die angegebene Anzahl von Meilen.

def__drin__(selbst, Kilometerstand):
 self.mileage = Laufleistung
defAntrieb(selbst, Meilen):

 Fährt das Auto für die angegebene Anzahl von Meilen.
 Argumente:
 miles (float): Die Anzahl der zu fahrenden Meilen.
 Kehrt zurück:
Keiner

 self.mileage += Meilen

Der Docstring für die obige Klasse beschreibt, was die Klasse darstellt, ihre Attribute und ihre Methoden. In der Zwischenzeit liefern die Docstrings für die Laufwerksmethode Informationen darüber, was die Methode tut, welche Argumente sie erwartet und was sie zurückgibt.

Dies macht es für jeden, der mit dieser Klasse arbeitet, einfacher zu verstehen, wie man sie verwendet. Zu den weiteren Vorteilen der Verwendung von Docstrings gehören:

• Code-Wartbarkeit: Durch die Bereitstellung einer klaren Beschreibung der Funktionsweise des Codes helfen Docstrings Entwicklern, den Code zu ändern und zu aktualisieren, ohne Fehler einzuführen.
• Einfachere Zusammenarbeit: Wenn mehrere Entwickler an derselben Codebasis zusammenarbeiten – beispielsweise mit dem Live-Freigabetool von Visual Studio—docstrings ermöglichen es Entwicklern, den Code konsistent zu dokumentieren, damit jeder im Team ihn verstehen kann.
• Verbesserte Lesbarkeit des Codes: Docstrings bieten eine allgemeine Zusammenfassung dessen, was der Code zulässt jeder, der den Code liest, um seinen Zweck schnell zu verstehen, ohne den gesamten Code durchgehen zu müssen Block.

Docstring-Formate

Ein guter Docstring sollte beschreiben, was ein Stück Code tut, welche Argumente es erwartet und falls nötig Implementierungsdetails. Es sollte insbesondere alle Grenzfälle enthalten, die jeder, der den Code verwendet, kennen sollte.

Ein grundlegendes Docstring-Format hat die folgenden Abschnitte:

• Zusammenfassungszeile: Eine einzeilige Zusammenfassung dessen, was der Code tut.
• Argumente: Informationen zu den Argumenten, die die Funktion erwartet, einschließlich ihrer Datentypen.
• Rückgabewert: Informationen über den Rückgabewert der Funktion inklusive ihres Datentyps.
• Raises (optional): Informationen zu allen Ausnahmen, die die Funktion auslösen kann.

Dies ist nur ein grundlegendes Format, da es andere Formate gibt, die Sie als Grundlage für Ihre Dokumentzeichenfolgen auswählen können. Die beliebtesten sind Epytext, reStructuredText (auch bekannt als reST), NumPy und Google Docstrings. Jedes dieser Formate hat seine eigene Syntax, wie in den folgenden Beispielen gezeigt:

Epytext

Ein Docstring, der dem Epytext-Format folgt:

defmultiplizieren(a, b):

 Multipliziere zwei Zahlen miteinander.
 @param a: Die erste zu multiplizierende Zahl.
 @type a: int
 @param b: Die zweite zu multiplizierende Zahl.
 @Typ b: int
 @return: Das Produkt der beiden Zahlen.
 @rtype: int

zurückkehren a*b

reStructuredText (reST)

Ein Docstring, der dem reST-Format folgt:

defmultiplizieren(a, b):

 Multipliziere zwei Zahlen miteinander.
 :param a: Die erste zu multiplizierende Zahl.
 :tippe a: int
 :param b: Die zweite zu multiplizierende Zahl.
 :Typ b: int
 :zurückkehren: Das Produkt der beiden Zahlen.
 :rtyp: int

zurückkehren a*b

NumPy

Ein Docstring, der dem NumPy-Format folgt:

defmultiplizieren(a, b):

 Multipliziere zwei Zahlen miteinander.
 Parameter

 a: int
 Die erste zu multiplizierende Zahl.
 b: int
 Die zweite zu multiplizierende Zahl.
 Kehrt zurück

 int
 Das Produkt der beiden Zahlen.

zurückkehren a*b

Google

Ein Docstring, der dem Google-Format folgt:

defmultiplizieren(a, b):

 Multipliziere zwei Zahlen miteinander.
 Argumente:
 a (int): Die erste zu multiplizierende Zahl.
 b (int): Die zweite zu multiplizierende Zahl.
 Kehrt zurück:
 int: Das Produkt der beiden Zahlen.

zurückkehren a*b

Obwohl alle vier Docstring-Formate eine nützliche Dokumentation für die Multiplikationsfunktion bieten, sind die Formate NumPy und Google einfacher zu lesen als die Formate Epytext und reST.

So fügen Sie Tests in die Docstrings ein

Mit dem Modul doctest können Sie Testbeispiele in Ihre Docstrings einfügen. Das Modul doctest durchsucht den docstring nach Text, der wie interaktive Python-Sitzungen aussieht, und führt sie dann aus, um zu überprüfen, ob sie ordnungsgemäß funktionieren.

Um doctests zu verwenden, schließen Sie die Beispieleingaben und erwarteten Ausgaben in die Docstring ein. Nachfolgend finden Sie ein Beispiel dafür, wie Sie das tun würden:

defmultiplizieren(a, b):

 Multipliziere zwei Zahlen miteinander.
 Parameter

 a: int
 Die erste zu multiplizierende Zahl.
 b: int
 Die zweite zu multiplizierende Zahl.
 Kehrt zurück

 int
 Das Produkt der beiden Zahlen.
 Beispiele

 >>> multiplizieren (2, 3)
6
 >>> multiplizieren (0, 10)
0
 >>> multiplizieren (-1, 5)
-5

zurückkehren a*b

Der Beispiele Abschnitt enthält drei Funktionsaufrufe mit unterschiedlichen Argumenten und gibt jeweils die erwartete Ausgabe an. Wenn Sie das Doctest-Modul wie unten gezeigt ausführen, führt es die Beispiele aus und vergleicht die tatsächliche Ausgabe mit der erwarteten Ausgabe.

python -m doctest multiplizieren.py

Wenn es Unterschiede gibt, meldet das Doctest-Modul diese als Fehler. Durch die Verwendung von doctests mit solchen docstrings können Sie überprüfen, ob der Code wie erwartet funktioniert. Beachten Sie, dass Dokumenttests kein Ersatz für umfassendere Tests sind Unit-Tests und Integrationstests für Ihren Python-Code.

So generieren Sie Dokumentation aus Docstrings

Sie haben die Grundlagen der Verwendung von Docstrings zum Dokumentieren Ihres Python-Codes und die Bedeutung einer qualitativ hochwertigen Dokumentation gelernt. Um es noch besser zu machen, möchten Sie vielleicht eine Dokumentation für Ihre Module und Funktionen aus ihren jeweiligen Docstrings generieren.

Einer der beliebtesten Dokumentationsgeneratoren, die Sie verwenden können, ist Sphinx. Es unterstützt standardmäßig das reST-Docstring-Format, aber Sie können es so konfigurieren, dass es mit dem Google- oder NumPy-Format funktioniert.