Stell dir vor, du öffnest ein Projekt, das du vor einem halben Jahr geschrieben hast, und findest eine Funktion, deren Zweck dir nicht mehr einfällt. Genau hier setzen Docstrings an. Sie sind kurze Beschreibungen direkt im Quellcode, die erklären, was eine Funktion tut. Du profitierst davon nicht nur, wenn andere Entwickler deinen Code lesen, sondern auch dann, wenn du allein an einem Projekt arbeitest. In dieser Anleitung lernst du, wie du Docstrings anlegst, mehrzeilig formatierst und anschließend direkt in der Python-Konsole abrufst.
Wichtigste Erkenntnisse
- Ein Docstring ist ein String, der direkt unter der Zeile steht, in der die Funktion definiert wird.
- Für kurze Beschreibungen reicht eine Zeile in einfachen oder doppelten Anführungszeichen. Längere Texte schreibst du mit dreifachen Anführungszeichen über mehrere Zeilen.
- Mit der Funktion
help()kannst du den Docstring jederzeit in der Konsole anzeigen lassen. - Docstrings lohnen sich schon bei kleinen Funktionen. Am besten werden sie zu einer festen Gewohnheit.
Schritt-für-Schritt-Anleitung
Schritt 1: Die Ausgangsfunktion betrachten
Als Grundlage dient eine einfache Funktion namens addieren. Sie nimmt zwei Parameter, x und y, entgegen und gibt deren Summe zurück. Der Code selbst ist schnell verstanden. Genau das macht ihn aber zum idealen Beispiel, denn du siehst sofort, wie viel Platz für eine Beschreibung vorhanden ist, bevor die eigentliche Logik beginnt. Die Stelle direkt nach der def-Zeile ist dafür reserviert.

Schritt 2: Einen einzeiligen Docstring anlegen
Schreibe direkt unter die Zeile def addieren(x, y): einen String, der beschreibt, was die Funktion macht. Ein passender Satz wäre etwa „Addiert zwei Zahlen und gibt das Ergebnis zurück.“ Der String wird eingerückt, sodass er zum Funktionsrumpf gehört. Er wird beim Ausführen des Programms nicht berechnet und hat keinen Einfluss auf das Ergebnis.
Schritt 3: Mehrzeilige Docstrings mit dreifachen Anführungszeichen formulieren
Wird die Beschreibung länger, etwa weil du Parameter oder Besonderheiten erklären möchtest, wird eine einzelne Zeile schnell unübersichtlich. Verwende dann dreifache Anführungszeichen. Damit kannst du den Text über mehrere Zeilen verteilen, ohne jede Zeile gesondert kennzeichnen zu müssen. Der Docstring beginnt und endet mit """, und dazwischen schreibst du frei formulierten Text. So bleibt der Quellcode auch bei umfangreicheren Erklärungen gut lesbar.
Schritt 4: Die Dokumentation für spätere Tools vorbereiten
Ein Docstring hilft nicht nur beim Lesen des Codes. Externe Werkzeuge können ihn auslesen und daraus automatisch eine Dokumentation erzeugen. Das ist besonders dann nützlich, wenn ein Projekt wächst und viele Funktionen zusammenkommen. Wenn du die Beschreibungen konsequent direkt im Quellcode hinterlegst, musst du sie später nicht mühsam aus verschiedenen Dateien zusammensuchen. Die Dokumentation wandert also mit dem Code mit, statt in einem separaten Dokument zu veralten.

Schritt 5: Den Docstring von print in der Konsole abrufen
Bevor du eigene Funktionen dokumentierst, lohnt sich ein Blick auf eingebaute Funktionen. Starte dazu die Python-Konsole und gib help(print) ein. Python zeigt dir daraufhin die Hilfe zur Funktion print an. Genau dieser Text ist der Docstring von print. Du siehst also, wie eine gut dokumentierte Funktion aussieht, und bekommst direkt eine Vorstellung davon, welche Informationen für andere hilfreich sind.

Schritt 6: Den eigenen Docstring mit help() anzeigen
Nachdem du die Funktion addieren mit Docstring in die Konsole übernommen hast, kannst du sie ebenfalls mit help(addieren) abfragen. Die Ausgabe enthält zuerst einen Hinweis auf die Parameter, also x und y. Danach folgt der Text aus dem Docstring. Du musst den Code also nicht öffnen, um zu wissen, was die Funktion tut. Das ist ein großer Vorteil, wenn du mit Funktionen aus größeren Projekten arbeitest.
Schritt 7: Die Ausgabe der Hilfe richtig lesen
Die Hilfe-Ausgabe ist nach einem festen Muster aufgebaut. Oben steht die Signatur der Funktion mit ihren Parametern. Darunter erscheint der Text, den du im Docstring hinterlegt hast. Achte darauf, dass dein Text präzise formuliert ist, denn genau dieser Wortlaut landet in der Ausgabe. Eine Beschreibung wie „addiert zwei Zahlen und gibt das Ergebnis zurück“ ist kurz, verständlich und sagt alles Wesentliche aus.
Schritt 8: Den richtigen Umfang für Docstrings finden
Nicht jede Funktion braucht einen ausführlichen Docstring. Bei zwei Zeilen Code, die ohnehin selbsterklärend sind, reicht oft ein kurzer Satz. Je länger oder komplexer eine Funktion wird und je weniger der Zweck sofort ersichtlich ist, desto wichtiger ist eine ausführliche Dokumentation. Du musst dabei eine Balance finden. Ein überladener Docstring bei einer simplen Funktion wirkt genauso unübersichtlich wie ein fehlender Docstring bei einer komplexen.
Schritt 9: Dokumentieren zur Gewohnheit machen
Am Ende entscheidet die Routine. Gewöhne dich daran, bei jeder neuen Funktion direkt einen Docstring zu schreiben, auch wenn du das Projekt allein bearbeitest. Die Mühe ist gering, der Nutzen zeigt sich spätestens dann, wenn du nach längerer Zeit wieder in deinen Code schaust. Wenn du den Docstring unmittelbar beim Schreiben der Funktion ergänzt, geht dir die Erklärung nicht verloren.
Zusammenfassung – Docstrings in Python: Funktionen richtig dokumentieren
Docstrings sind Beschreibungen, die du direkt unter einer Funktionsdefinition hinterlegst. Für kurze Erklärungen reicht eine Zeile, für längere Texte nutzt du dreifache Anführungszeichen. Mit help() zeigst du die Dokumentation in der Konsole an, und externe Tools können sie auslesen und daraus eine Dokumentation erzeugen. Du solltest Docstrings von Anfang an schreiben, dabei den Umfang an die Komplexität der Funktion anpassen und so eine feste Gewohnheit entwickeln.
FAQ
Was ist ein Docstring in Python?Ein Docstring ist ein String, der direkt nach der Definition einer Funktion steht und deren Zweck beschreibt.
Wann sollte ich einen Docstring schreiben?Schon bei einfachen Funktionen ist er sinnvoll, besonders aber bei umfangreichem Code oder wenn der Zweck nicht sofort erkennbar ist.
Wie rufe ich einen Docstring auf?Du nutzt die Funktion help() in der Python-Konsole, zum Beispiel help(addieren) oder help(print).
Welche Anführungszeichen verwende ich für mehrzeilige Docstrings?Du verwendest dreifache Anführungszeichen, also """ am Anfang und am Ende des Textes.
Beeinflusst ein Docstring das Ergebnis meines Programms?Nein, der Docstring wird nicht berechnet und hat keinen Einfluss auf das Ergebnis der Funktion.
