Python Docstrings verstehen: Anleitung, Beispiele & Best Practices

1. Was ist ein docstring in Python?

Ein docstring in Python ist ein spezieller String, der einer Funktion, Klasse oder einem Modul hinzugefügt wird, um eine Erklärung bereitzustellen. docstring verbessert die Wartbarkeit des Codes und spielt eine entscheidende Rolle dabei, anderen Entwicklern das Verständnis des Codes zu erleichtern. Zudem können automatische Dokumentations-Tools (z. B. Sphinx), die später erläutert werden, genutzt werden, um mit Hilfe von docstring Dokumentationen zu generieren.

Position und Format von docstrings

Ein docstring wird direkt nach der Definition einer Funktion, Klasse oder eines Moduls eingefügt und standardmäßig in dreifachen Anführungszeichen notiert. Die allgemeine Syntax sieht wie folgt aus:

def funktionsname(argumente):
    """
    Kurze Beschreibung der Funktion.

    Argumente:
        argumentname (Typ): Detaillierte Beschreibung des Arguments
    Rückgabewert:
        Typ: Erklärung des Rückgabewerts
    """
    pass

docstring wird unter anderem von der eingebauten Python-Funktion help() sowie von Editor-Tooltips genutzt und dient damit als wichtige Grundlage für die Dokumentation des Codes.

2. Grundlagen der docstring-Syntax

Ein Python-docstring wird verwendet, um die Spezifikation einer Funktion oder Klasse kurz und klar zu beschreiben. Das Format beginnt in der Regel mit einer kurzen Beschreibung des Zwecks, gefolgt von Angaben zu Argumenten, Rückgabewerten oder möglichen Fehlern. Durch die Einhaltung der offiziellen Style-Guidelines von PEP 257 wird Konsistenz geschaffen, was die Verständlichkeit für andere Entwickler deutlich erhöht.

Grundstruktur eines docstrings

Ein einzeiliger docstring wird genutzt, wenn eine sehr kurze Beschreibung genügt – typischerweise zur Erklärung der Funktion in einem Satz:

def add(a, b):
    """Addiert zwei Zahlen und gibt das Ergebnis zurück."""
    return a + b

Mehrzeilige docstrings werden genutzt, wenn eine detailliertere Erklärung erforderlich ist. Hierbei werden die Funktionsweise, Argumente und Rückgabewerte präzise beschrieben und durch Absätze für bessere Lesbarkeit strukturiert:

def add(a, b):
    """
    Addiert zwei Zahlen und gibt das Ergebnis zurück.

    Argumente:
        a (int): Erste Zahl, die addiert wird
        b (int): Zweite Zahl, die addiert wird

    Rückgabewert:
        int: Die Summe der beiden Zahlen
    """
    return a + b

3. docstring-Stile (Google-Stil, NumPy-Stil, reStructuredText-Stil)

Die Formatierung von docstring kann je nach Projekt oder eingesetzten Tools variieren. Besonders verbreitet sind die drei Stile: Google-Stil, NumPy-Stil und reStructuredText-Stil.

Google-Stil

Der Google-Stil zeichnet sich durch eine klare und leicht verständliche Struktur aus. Argumente und Rückgabewerte werden unter den Abschnitten Args und Returns aufgeführt, wodurch sich die Funktionserklärung schnell erfassen lässt.

def add(a, b):
    """
    Addiert zwei Zahlen und gibt das Ergebnis zurück.

    Args:
        a (int): Erste Zahl, die addiert wird
        b (int): Zweite Zahl, die addiert wird

    Returns:
        int: Die Summe der beiden Zahlen
    """
    return a + b

NumPy-Stil

Der NumPy-Stil bietet ein noch detaillierteres Format und wird insbesondere in wissenschaftlicher Berechnung und Datenanalyse häufig eingesetzt. Abschnitte wie Parameters und Returns strukturieren die Angaben zu Argumenten und Rückgabewerten.

def add(a, b):
    """
    Addiert zwei Zahlen und gibt das Ergebnis zurück.

    Parameters
    ----------
    a : int
        Erste Zahl, die addiert wird
    b : int
        Zweite Zahl, die addiert wird

    Returns
    -------
    int
        Die Summe der beiden Zahlen
    """
    return a + b

reStructuredText-Stil

Der reStructuredText-Stil wird vor allem mit dem Dokumentations-Tool Sphinx verwendet. In komplexeren Projekten ist er weit verbreitet, da Sphinx daraus automatisch HTML- oder PDF-Dokumentationen erzeugen kann.

def add(a, b):
    """
    Addiert zwei Zahlen.

    :param a: Erste Zahl, die addiert wird
    :type a: int
    :param b: Zweite Zahl, die addiert wird
    :type b: int
    :return: Die Summe der beiden Zahlen
    :rtype: int
    """
    return a + b

4. PEP 257 und Best Practices

PEP 257 ist der offizielle Style Guide für docstring in Python. Er bietet klare Richtlinien zur Schreibweise von docstring, die die Lesbarkeit verbessern und es sowohl anderen Entwicklern als auch einem selbst erleichtern, den Code nachzuvollziehen.

Wichtige Punkte aus PEP 257

1. Einzeilige docstrings
   Für einfache Funktionen oder Methoden wird empfohlen, eine kurze, prägnante Erklärung in einer Zeile zu schreiben.
2. Mehrzeilige docstrings
   Wenn eine detailliertere Erklärung erforderlich ist, sollte ein mehrzeiliger docstring verwendet werden. Dabei beginnt die erste Zeile mit einer kurzen Zusammenfassung, gefolgt von einer Leerzeile und dann einer ausführlicheren Erklärung.
3. Einrückung und Leerzeilen
   Innerhalb eines docstring sollen Zeilenumbrüche und Einrückungen für bessere Lesbarkeit genutzt werden. Angaben zu Argumenten und Rückgabewerten sollten klar voneinander getrennt sein.

Best Practices

• Kurz und präzise formulieren
  Ein docstring sollte klar und prägnant erklären, was eine Funktion oder Klasse macht. Unnötige Details sind zu vermeiden, wichtige Informationen jedoch detailliert zu beschreiben.
• Einheitlichen Stil beibehalten
  Der Stil der docstrings sollte im gesamten Projekt konsistent sein. Ob Google-Stil, NumPy-Stil oder reStructuredText-Stil – entscheidend ist, dass einheitliche Regeln für das Team oder Projekt gelten.

5. Tests mit docstring (doctest)

Python bietet mit dem Modul doctest die Möglichkeit, Beispiele im docstring automatisch zu testen. So kann überprüft werden, ob der enthaltene Beispielcode wie erwartet funktioniert. Dadurch steigt die Zuverlässigkeit des Codes und Dokumentation und Implementierung bleiben konsistent.

Grundlegende Nutzung von doctest

doctest erkennt automatisch Codebeispiele in docstrings und überprüft, ob die Ergebnisse mit den beschriebenen Ausgaben übereinstimmen. Das folgende Beispiel zeigt die Einbindung von doctest in einem if __name__ == "__main__":-Block:

def add(a, b):
    """
    Addiert zwei Zahlen und gibt das Ergebnis zurück.

    Args:
        a (int): Erste Zahl
        b (int): Zweite Zahl

    Returns:
        int: Die Summe der beiden Zahlen

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Im obigen Beispiel führt doctest den Code aus dem docstring aus und vergleicht die Ergebnisse mit den erwarteten Ausgaben. Bei Erfolg wird nichts ausgegeben, im Fehlerfall erscheint eine Fehlermeldung.

Vorteile von doctest

1. Konsistenz zwischen Code und Dokumentation
   Mit doctest wird sichergestellt, dass die im docstring enthaltenen Beispiele tatsächlich funktionieren. So bleibt die Dokumentation immer synchron mit dem aktuellen Code.
2. Automatisierte Tests
   doctest lässt sich leicht automatisieren. Alle Beispiele in den docstrings werden mit einem einzigen Lauf geprüft, wodurch Fehler schneller erkannt werden.

6. Praxisbeispiel: Dokumentation von Code mit docstring

Durch den Einsatz von docstring kann Python-Code erheblich an Lesbarkeit gewinnen und für andere Entwickler verständlicher werden. In diesem Abschnitt wird gezeigt, wie man Klassen und Funktionen mit docstring versieht und diese anschließend mit Sphinx automatisch dokumentiert.

Beispiel für docstrings in Klassen

Auch Klassen und deren Methoden sollten mit docstring versehen werden. Der Klassen-docstring beschreibt, welche Funktionalität die Klasse bereitstellt, während die Methoden-docstrings detaillierte Erklärungen zu den einzelnen Methoden enthalten.

class Calculator:
    """
    Eine einfache Taschenrechner-Klasse.

    Diese Klasse unterstützt grundlegende Operationen wie Addition, Subtraktion,
    Multiplikation und Division.

    Attribute:
        result (int): Variable zur Speicherung des Ergebnisses
    """

    def __init__(self):
        """
        Konstruktor der Calculator-Klasse.
        Initialisiert das Ergebnis mit 0.
        """
        self.result = 0

    def add(self, a, b):
        """
        Addiert zwei Zahlen und gibt das Ergebnis zurück.

        Args:
            a (int): Erste Zahl
            b (int): Zweite Zahl

        Returns:
            int: Die Summe der beiden Zahlen
        """
        self.result = a + b
        return self.result

In diesem Beispiel enthält die Klasse eine allgemeine Beschreibung sowie eigene docstrings für den Konstruktor __init__ und die Methode add. Dadurch kann ein Nutzer der Klasse schnell nachvollziehen, wie sie funktioniert.

Dokumentation mit Sphinx

Mit Sphinx lassen sich aus docstrings automatisch HTML- oder PDF-Dokumente generieren. Zunächst wird Sphinx im Projekt installiert und konfiguriert (z. B. über die Datei conf.py). Anschließend erstellt der Befehl make html eine vollständige HTML-Dokumentation aus den vorhandenen Python-Dateien.

Installation von Sphinx:

pip install sphinx

Initialisierung des Projekts mit:

sphinx-quickstart

Nach der Einrichtung können die in den Python-Dateien enthaltenen docstrings automatisch in die Dokumentation übernommen werden.

7. Häufige Fehler und wie man sie vermeidet

Beim Schreiben von docstrings machen Anfänger oft typische Fehler. In diesem Abschnitt werden die häufigsten Probleme und deren Lösungen vorgestellt.

1. Unklare oder vage Beschreibungen

docstrings sollten klar und präzise formuliert sein. Vage Erklärungen helfen dem Leser nicht weiter. Zum Beispiel ist der folgende docstring unzureichend:

def add(a, b):
    """Addiert zwei Zahlen."""
    return a + b

Hier fehlen Informationen zu Argumenten und Rückgabewerten. Eine bessere Variante wäre:

def add(a, b):
    """
    Addiert zwei ganze Zahlen und gibt das Ergebnis zurück.

    Args:
        a (int): Erste Zahl
        b (int): Zweite Zahl

    Returns:
        int: Die Summe der beiden Zahlen
    """
    return a + b

2. Ungenaue Angaben zu Argumenten oder Rückgabewerten

Wenn in einem docstring keine detaillierten Angaben zu Parametern oder Rückgabewerten gemacht werden, können Nutzer die Funktion falsch verwenden. Besonders bei komplexeren Funktionen ist es wichtig, Datentypen und Bedeutungen klar zu definieren.

def divide(a, b):
    """Teilt zwei Zahlen."""
    return a / b

In diesem Beispiel fehlen Erklärungen zu den Argumenten und zu möglichen Fehlern. Eine bessere Variante wäre:

def divide(a, b):
    """
    Teilt zwei Zahlen und gibt das Ergebnis zurück. Bei einer Division durch 0
    wird ein ZeroDivisionError ausgelöst.

    Args:
        a (float): Dividend
        b (float): Divisor

    Returns:
        float: Ergebnis der Division

    Raises:
        ZeroDivisionError: Wenn der Divisor 0 ist
    """
    if b == 0:
        raise ZeroDivisionError("Division durch 0 ist nicht erlaubt")
    return a / b

Mit ausreichend Informationen im docstring wird sichergestellt, dass Nutzer den Code korrekt und ohne Missverständnisse verwenden können.

8. Fazit: Effiziente Dokumentation mit docstring

In diesem Artikel haben wir die Bedeutung von docstring in Python, deren Schreibweise, Stile und Best Practices behandelt. docstring ist ein zentrales Werkzeug, um die Lesbarkeit und Wartbarkeit von Code zu verbessern. Durch die Einhaltung der PEP-257-Richtlinien lassen sich konsistente und leicht verständliche Dokumentationen erstellen.

Darüber hinaus haben wir gesehen, wie man doctest für automatische Tests und Sphinx für die Generierung von Dokumentationen einsetzen kann. So wird nicht nur die Qualität des Codes gesteigert, sondern auch die Effizienz der Entwicklung verbessert.

Konsistente Dokumentation nach PEP 257

PEP 257 bietet klare Leitlinien für das Schreiben von docstrings. Durch die Kombination von einzeiligen docstrings für einfache Funktionen und mehrzeiligen docstrings für komplexere Beschreibungen lässt sich die Absicht des Codes präzise vermitteln.

Automatisierte Tests mit doctest

Mit doctest können die im docstring enthaltenen Beispiele automatisch getestet werden. Dadurch bleibt die Dokumentation konsistent mit dem Code und mögliche Fehler werden frühzeitig erkannt.

Automatische Dokumentation mit Sphinx

Mit Tools wie Sphinx können aus docstrings automatisch HTML- oder PDF-Dokumentationen generiert werden. Dies spart nicht nur Zeit, sondern stellt auch sicher, dass die Dokumentation stets auf dem neuesten Stand des Codes ist.