Die häufigsten Docstring-Muster in Python

Das Dokumentieren von Code ist eine gute Angewohnheit, und aufstrebende Entwickler und Programmierer sollten es sich zur Gewohnheit machen, ihren Code in den frühen Phasen ihrer Codierungsreise zu dokumentieren.

Das Dokumentieren eines Quellcodes verbessert die Lesbarkeit und Verwaltung des Quellcodes und macht es für neue Mitwirkende am Quellcode extrem einfach, ihn zu verstehen.

Docstrings sind Zeichenkettenliterale, die in Quellcodes geschrieben sind. Sie fungieren als Kommentare oder Dokumentation für Codeteile. Docstrings werden verwendet, um Klassen, Funktionen und manchmal sogar die Dateien zu beschreiben.

Mit anderen Worten, ein Docstring dient als Metadaten zu den Codeschnipseln. Ein Docstring enthält alle relevanten Informationen darüber, was sie beschreiben. Für eine Klasse enthält es Informationen über:

• die Klasse
• Klassenfunktionen
• Klassenattribute.

Für Funktionen enthält es Details über:

• Parameter
• Datentypen von Parametern
• Standardwerte der Parameter
• kurze Beschreibungen zu Parametern
• was die Funktion zurückgibt
• Datentyp dessen, was von der Funktion zurückgegeben wird
• Fehler und Ausnahmen, die die Funktion auslöst, und kurze Beschreibungen darüber

Es gibt mehrere Docstring-Muster, die professionelle Python-Entwickler verwenden, um ihren Code zu dokumentieren.

Anstatt die vorhandenen zu verwenden, kann man ihr Docstring-Muster erstellen. Diese Entscheidung hängt jedoch ausschließlich vom einzelnen Entwickler oder dem Entwicklerteam ab.

Dieser Artikel befasst sich mit den besten Docstring-Mustern für die Programmiersprache Python.

Docstring-Muster in Python

Im Folgenden sind einige der besten Docstring-Muster aufgeführt, die üblicherweise von Python-Profis in der Branche verwendet werden.

Epytext-Muster

Das Epytext-Muster ist ein Docstring-Muster ähnlich dem JavaDoc. Es ist ein Teil des Epydoc-Tools, das zum Generieren von Dokumentation für Python-Module unter Verwendung ihrer Docstrings verwendet wird. Es folgt ein Beispiel für das Epytext-Muster.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""

Oben steht eine kurze Beschreibung der Funktion.

Alle Funktionsparameter werden mit dem Schlüsselwort @param geschrieben. Eine Erklärung, was von der Funktion zurückgegeben wird, steht neben dem Schlüsselwort @return.

Wenn die Funktion Fehler oder Ausnahmen auslöst, werden sie mit dem Schlüsselwort @raise geschrieben.

reST-Muster

Der reSt oder reStructuredText ist ein Docstring-Muster, das von Sphinx verwendet wird, einem Tool zum Generieren von Dokumentation für die Programmiersprache Python. Dieses Muster ist eines der am häufigsten verwendeten Docstrings-Muster in der IT-Branche.

Diese Methode wird auch als Ausgabeformat in Pyment verwendet, einem Werkzeug, das Python-Programmierern hilft, erweiterte Codedokumentation mit Docstrings zu schreiben. Dieses Tool ist nützlich, wenn der Code teilweise dokumentiert ist oder keine Docstrings enthält.

Die PyCharm-IDE oder integrierte Entwicklungsumgebung von JetBrains verwendet ebenfalls das reST-Muster. Es folgt ein Beispiel für das reST-Muster.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""

Ähnlich wie beim Epytext-Muster ist bei diesem Muster alles gleich, außer dass es einen Doppelpunkt oder : als Präfix für Schlüsselwörter anstelle des At-Zeichens oder @ im Fall des Epytext-Musters verwendet.

Eine knappe oder umfassende Beschreibung der Methode steht ganz oben. Alle Parameter befinden sich neben dem Schlüsselwort :param. Eine Erläuterung dessen, was von der Methode zurückgegeben wird, steht neben dem Schlüsselwort :return.

Details zu allen Fehlern werden neben dem Schlüsselwort :raise platziert.

Google-Muster

Ein weiteres Muster auf der Liste ist das Google-Muster. Technisch gesehen ist sein Name kein Google-Muster, aber es ist ein Muster, das Google entwickelt hat.

Es ist ein sauberes Muster, das Details unter Überschriften organisiert. Das Sphinx-Tool ist in der Lage, auch dieses Muster zu erkennen und eine Dokumentation zu erstellen.

Dieses Muster ist auch eines der Docstrings-Muster. Im Folgenden finden Sie ein Beispiel für das Google-Muster.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Args:
    parameter1: this is the first parameter.
    parameter2: this is the second parameter.

Returns:
    this is a description of what is returned by the function.

Raises:
    KeyError: raises an exception.
    TypeError: raises an exception.
"""

Wie bei den vorherigen Mustern befindet sich oben eine kurze Beschreibung der Methode.

Der Beschreibung folgen Überschriften wie Args, Returns und Raises. Unter der Überschrift Args sind alle Parameter und Details wie deren Typ und Standardwerte platziert.

Eine Beschreibung dessen, was von der Funktion zurückgegeben wird, befindet sich unter der Überschrift Returns. Schließlich werden Fehler oder Ausnahmen und ihre Details unter der Überschrift Raises aufgeführt.

Numpydoc-Muster

Das numpy-Modul hat seine Docstring-Muster, die als Numpydoc-Muster bekannt sind.

Dieses Muster ähnelt dem Google-Muster und wird vom Sphinx-Tool erkannt. Ähnlich wie beim Google-Muster werden Informationen unter Überschriften organisiert.

Es folgt ein Beispiel für das Numpydoc-Muster.

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Parameters
----------
parameter1 : int
    this is the first parameter.
parameter2 : str, "default value"
    this is the second parameter.

Returns
-------
string
    returns a string value.

Raises
------
KeyError
    raises an exception.
TypeError
    raises an exception.
"""

Die Beschreibung der Methode steht oben. Weitere Details zur Methode sind unter den Überschriften Parameter, Returns und Raises organisiert.

Alle Details zu den Parametern, einschließlich ihres Standardwerts, Werttyps usw., befinden sich unter der Überschrift Parameter. Alle Details darüber, was von der Funktion zurückgegeben wird, einschließlich des Datentyps, befinden sich unter der Überschrift Returns.

Schließlich werden Informationen über die Fehler oder Ausnahmen und einige Beschreibungen unter der Überschrift Raises geschrieben.