Docstring-Stilrichtlinien meistern: Standards setzen in Python

Im Laufe eines Softwareprojekts benötigt man oft umfassende und verständliche Dokumentation. Doch wie stellt man sicher, dass die Dokumentation einheitlich und verständlich ist? Eine wichtige Methode ist die Verwendung von Docstrings, die von PEP 257 vorgegebenen Standards folgen. In diesem Blogpost geht es darum, wie man Docstrings korrekt und konsistent für eine bestehende Python-Bibliothek gestaltet. Du lernst verschiedene Methoden kennen, um Docstrings zu schreiben, und am Ende werden wir Tools einsetzen, um die Konsistenz deiner Dokumentation zu überprüfen.

Docstrings: Grundlagen und Stilrichtlinien

Docstrings sind Kommentare, die zur Dokumentation einer Funktion, Klasse oder eines Moduls genutzt werden. Sie werden direkt nach der Definition unter Verwendung von dreifachen Anführungszeichen geschrieben. Schauen wir uns zuerst die grundlegenden Stilrichtlinien an, die von PEP 257 empfohlen werden:

• Einfache Beschreibungen sollten im Imperativ geschrieben sein.
• Die erste Zeile sollte eine kurze Zusammenfassung bieten.
• Falls nötig, sollte ein detaillierterer Abschnitt nach einer Leerzeile folgen.
• Nutze konsistente Einrückungen, die mit dem gesamten Python-Code übereinstimmen.

Beispiel: Eine einfache Funktion mit Docstring

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

    Nimmt zwei Argumente an, 'a' und 'b', und gibt ihre Summe zurück.

    :param a: Die erste Zahl
    :param b: Die zweite Zahl
    :return: Die Summe von 'a' und 'b'
    """
    return a + b
Code-Sprache: Python (python)

Erweiterte Docstring-Struktur

Für umfangreiche Funktionen oder Klassen kannst du Docstrings erweitern, um komplexere Informationen bereitzustellen.

Klasse mit erweitertem Docstring

class Calculator:
    """
    Eine einfache Rechenmaschine.

    Diese Klasse bietet Methoden, um grundlegende mathematische Operationen
    wie Addition und Multiplikation durchzuführen.
    """

    def multiply(self, x, y):
        """
        Multipliziert zwei Zahlen.

        :param x: Der erste Multiplikand
        :param y: Der zweite Multiplikand
        :return: Das Produkt von 'x' und 'y'
        """
        return x * y
Code-Sprache: Python (python)

Verschiedene Stile von Docstrings

Es gibt verschiedene Formate, die genutzt werden können, um zusätzliche Informationen bereitzustellen. Die gebräuchlichsten sind:

• Google-Stil
• NumPy-Stil
• reStructuredText-Stil

Hier ist ein Beispiel für den Google-Stil:

def divide(a, b):
    """
    Dividiert zwei Zahlen.

    Args:
        a (int, float): Der Divident.
        b (int, float): Der Divisor (darf nicht 0 sein).

    Returns:
        float: Das Ergebnis der Division.

    Raises:
        ValueError: Wenn 'b' gleich 0 ist.
    """
    if b == 0:
        raise ValueError("Der Divisor darf nicht 0 sein.")
    return a / b
Code-Sprache: Python (python)

Bewertung und Überprüfung mit Tools

Um sicherzustellen, dass die Docstrings einheitlich und stilistisch korrekt sind, kannst du Tools wie pydocstyle verwenden. Installiere es mit:

pip install pydocstyleCode-Sprache: Bash (bash)

Nach der Installation kannst du es für deine Bibliothek verwenden:

pydocstyle pfad/zu/deiner_bibliothek/Code-Sprache: Python (python)

Dies liefert eine Auflistung von Stellen, an denen die Docstrings nicht den PEP 257-Richtlinien entsprechen.

Weiterführende Links

• PEP 257 – Docstring Conventions
• Google Python Style Guide
• NumPy Documentation Guidelines
• pydocstyle Documentation

Durch das Verständnis und Anwenden dieser Techniken kannst du für eine saubere und konsistente Dokumentation deiner Python-Projekte sorgen.