Wie man einen effektiven Docstring in Python für klareren Code schreibt

Wie man einen effektiven Docstring in Python für klareren Code schreibt

von Ajaymaurya

Aug 26, 2025

Quelle: https://medium.com/@ajaymaurya73130/how-to-write-an-effective-docstring-in-python-for-clearer-code-01221dc88e2f
Mit DeepL.com übersetzt

Stellen Sie sich vor, Sie öffnen ein Python-Projekt sechs Monate, nachdem Sie es geschrieben haben, und stellen fest, dass Sie sich nicht daran erinnern können, warum Sie die Hälfte der Funktionen erstellt haben. Frustrierend, oder? Das ist der Punkt, an dem Docstrings in Python ins Spiel kommen. Ein gut geschriebener Docstring verwandelt verwirrenden Code in etwas Klares, Lesbares und Professionelles. Es ist nicht nur für andere - es ist für Ihre Zukunft.

In diesem Leitfaden erfahren Sie, was Docstrings sind, warum sie wichtig sind und wie man sie effektiv schreibt. Sie erhalten praktische Beispiele, Stiltipps und Best Practices, mit denen Ihr Code glänzen wird. Tauchen wir ein! Was ist ein Docstring in Python?

Ein Docstring (kurz für Dokumentationsstring) ist eine spezielle mehrzeilige Zeichenkette, die verwendet wird, um zu erklären, was ein Modul, eine Klasse, eine Funktion oder eine Methode tut. Im Gegensatz zu Kommentaren, die vollständig ignoriert werden, werden Dokumentationsstrings im Codeobjekt selbst gespeichert. Das bedeutet, dass Werkzeuge wie help() oder Dokumentationsgeneratoren direkt auf sie zugreifen können.

Zum Beispiel:

python

def greet(name):
    """Return a friendly greeting with the provided name."""
    return f"Hello, {name}!"

Hier erklärt die Zeichenkette in drei Anführungszeichen, was die Funktion tut. Wenn Sie help(greet) ausführen, wird der Docstring automatisch angezeigt. Warum sind Docstrings wichtig?

Klare Dokumentationsstrings sind für jedes Projekt von großem Wert. Sie:

• Verbessern Sie die Lesbarkeit, indem Sie erklären, was der Code tut, ohne sich in Details zu verlieren.
• Sie helfen neuen Entwicklern, sich schneller einzuarbeiten, wenn sie die Funktionen schnell verstehen.
• Erstellen Sie eine automatisch generierte Dokumentation mit Tools wie Sphinx oder Pydoc.
• Bessere Zusammenarbeit bei der Arbeit an großen Softwareprojekten.
• Sie dienen als Mini-Leitfaden für die künftige Pflege Ihrer eigenen Codebasis.

Betrachten Sie docstrings als das Benutzerhandbuch Ihres Codes - ohne sie lassen Sie die Leser im Dunkeln tappen.

Effektive Docstrings schreiben: Die Grundlagen

Bevor wir uns mit den Stilen befassen, wollen wir uns auf die Grundlagen guter Dokumentationsstrings konzentrieren:

• Beginnen Sie mit einer einzeiligen Zusammenfassung, die den Zweck klar erläutert.
• Wenn nötig, folgen weitere Details über Parameter, Rückgabewerte und Verwendung.
• Seien Sie prägnant, aber beschreibend - vermeiden Sie Fluff, aber geben Sie genügend Klarheit.
• Verwenden Sie einen einheitlichen Stil in Ihrem Projekt, um Verwirrung zu vermeiden.

Beispiel mit etwas mehr Struktur:

python

def calculate_area(length, width):
    """
    Calculate the area of a rectangle.

    Args:
        length (int or float): The length of the rectangle.
        width (int or float): The width of the rectangle.

    Returns:
        float: The calculated area of the rectangle.
    """
    return length * width

Beliebte Docstring-Stile in Python

Obwohl Python kein bestimmtes Format vorschreibt, dominieren drei Stile bei professionellen Projekten:

Google Style

Lesbar und übersichtlich.

python

def add_numbers(a, b):
    """
    Add two numbers together.

    Args:
        a (int): First number.
        b (int): Second number.

    Returns:
        int: The sum of a and b.
    """
    return a + b

NumPy Style

Wird oft in wissenschaftlichen und datenintensiven Projekten verwendet.

python

def multiply(a, b):
    """
    Multiply two numbers.

    Parameters
    ----------
    a : int
        First number.
    b : int
        Second number.

    Returns
    -------
    int
        The product of a and b.
    """
    return a * b

reStructuredText (reST) Style

Leistungsfähig in Verbindung mit Sphinx zur Erstellung von Dokumenten.

python

def divide(a, b):
    """
    Divide one number by another.

    :param a: Numerator
    :type a: int
    :param b: Denominator
    :type b: int
    :return: Result of division
    :rtype: float
    :raises ZeroDivisionError: If b is zero
    """
    return a / b

Bewährte Praktiken für das Schreiben von Docstrings

Hier finden Sie einige bewährte Methoden, um sicherzustellen, dass Ihre Dokumentationsunterlagen wertvoll sind:

• Verwenden Sie immer dreifache Anführungszeichen, um Docstrings in Python konsequent zu schreiben.
• Die erste Zeile sollte eine kurze Zusammenfassung sein, die in einen Satz passt.
• Geben Sie Einzelheiten zu Argumenten, Rückgabetypen und ausgelösten Ausnahmen deutlich an.
• Verfassen Sie Dokumentationsstrings in einfachem Englisch, das auch Nicht-Experten verstehen können.
• Bleiben Sie über das gesamte Projekt hinweg immer bei einem gewählten Stil.
• Aktualisieren Sie die Dokumentationen bei jeder Änderung der Codelogik, um spätere Unklarheiten zu vermeiden.

Verwendung von Tools zur Durchsetzung der Docstring-Qualität

Es kann schwierig sein, Docstrings manuell konsistent zu halten. Zum Glück gibt es in Python Werkzeuge, die dabei helfen:

Pydoc

Eingebautes Werkzeug, das Docstrings in die Dokumentation extrahiert.

Sphinx mit Napoleon-Erweiterung

Erzeugt professionelle Dokumentation aus Google- oder NumPy-Docstrings.

Ruff und pydocstyle

Linters, die fehlende oder schlecht formatierte Docstrings erkennen.

Doktest

Ermöglicht es Ihnen, interaktive Beispiele einzubinden, die gleichzeitig als Tests dienen.

Die Verwendung dieser Tools spart Zeit und gewährleistet, dass Ihre Dokumentation mit Ihrem Code wächst. Real-World Beispiel: Docstring in einer Klasse

Hier sehen Sie, wie Docstrings die Lesbarkeit von Klassen verbessern können:

python

class BankAccount:
    """
    A simple bank account class.

    Attributes:
        balance (float): The current balance of the account.
    """

    def __init__(self, balance=0):
        """
        Initialize a new bank account with an optional starting balance.

        Args:
            balance (float, optional): Initial account balance. Defaults to 0.
        """
        self.balance = balance

    def deposit(self, amount):
        """
        Deposit money into the account.

        Args:
            amount (float): The amount to deposit.

        Returns:
            float: Updated account balance.
        """
        self.balance += amount
        return self.balance

In diesem Beispiel wird deutlich, was die Klasse tut, welche Argumente sie akzeptiert und was sie zurückgibt - ohne dass man jede Zeile des Codes lesen muss.

Danke fürs Lesen