Python-Code dokumentieren – so geht's

Erfahre, warum Code-Dokumentation wichtig ist, und lerne Best Practices kennen. Nutze außerdem das Potenzial des Pydoc-Moduls für die Dokumentation.

Aktualisiert 18. Sept. 2026 · 14 Min. lesen

Mit KI erkunden

ChatGPT Claude Perplexity

Wenn du gerade erst mit Python startest und mehr lernen möchtest, mach den DataCamp-Kurs Intermediate Python.

pandas — Dokumentation der Python-Bibliothek Pandas mit Sphinx</a

Warum Projekt-Dokumentation relevant ist

Dokumentation ist ein zentraler Bestandteil jedes Projekts – unabhängig von der verwendeten Programmiersprache. Selbst wenn ein Projekt mit mehreren laufenden APIs von vielen Nutzenden verwendet wird, gilt es ohne Dokumentation als unvollständig. Stell dir als Entwickler vor, du willst ein Projekt reproduzieren oder einen Teil davon nutzen – ganz ohne Doku. Die Integration in deine Architektur wäre mühsam.

Gute Dokumentation macht dein Projekt erfolgreicher, denn wenn du dein Projekt oder deine Software veröffentlichst, willst du, dass sie genutzt wird. Bei Open-Source-Projekten gilt das umso mehr. Du möchtest außerdem, dass die Community beiträgt und dein Projekt weiter verbessert.

Der bekannte Schöpfer der Programmiersprache Python sagt: Code wird häufiger gelesen als geschrieben. Dieses Zitat unterstreicht, wie wichtig Dokumentation ist, damit andere deinen Code oder dein Projekt verstehen und einsetzen können.

Stell dir vor, du arbeitest bei XYZ, bist in der Kündigungsfrist, und dein Manager möchte, dass du das Projekt an eine Kollegin übergibst. Du machst zwar eine Wissensübergabe, aber was, wenn sie einen Teil des Codes nicht erfolgreich ausführen kann? Gründe gibt es viele – vielleicht passen die Binärdateien, auf denen dein Code läuft, nicht zur aktuellen OS-Version.

Was genau ist Dokumentation?

Dokumentation besteht aus mehreren Bausteinen. Sie sollte sinnvoll daran ausgerichtet sein und diese Elemente berücksichtigen, um als vollständige Dokumentation zu gelten.

Auf abstrakter Ebene gehören dazu:

Ein gut kommentierter Codebestand deines Projekts.
Einhaltung der Python-PEP-8-Codierstandards.
Konkrete Tutorials, wie das Projekt aufgebaut wurde – besonders bei Open Source mit Lernfokus.
Eine Anleitung zur Installation der benötigten Pakete und Module, ggf. ein technisches Datenblatt bei Hardwarebezug. Zum Beispiel: Wie installiere ich Anaconda, TensorFlow, Keras usw.
Laufende Diskussionen zum Projektfortschritt, die zur erfolgreichen Umsetzung beigetragen haben.
Referenzmaterial mit technischer Beschreibung des im Entwicklungsprozess verwendeten Tech-Stacks.
Die Architektur des Projekts bzw. der Softwarelösung.

Das sind nur einige Bausteine einer gut strukturierten, runden Dokumentation. Wichtig ist, diese Elemente klar zu trennen – so bleibt die Doku auch künftig leichter wartbar.

Ein Beispiel für eine umfassende Dokumentation mit den meisten der genannten Elemente ist die folgende:

Viele verwechseln Kommentieren mit Dokumentieren. Kommentare beschreiben deinen Code für Nutzer, Maintainer und dich selbst als spätere Referenz. Sie wirken auf Code-Ebene und sind ein Teilbereich der Dokumentation. Kommentare helfen Leserinnen und Lesern dabei,

deinen Code zu verstehen,
ihn selbsterklärend zu machen und
Zweck sowie Design nachzuvollziehen.

Denk daran: Da Python PEP‑8-Standards folgt, gelten diese auch für Kommentare. Die offizielle Python-Doku empfiehlt für längere Fließtexte mit wenigen Strukturvorgaben (Docstrings oder Kommentare) eine maximale Zeilenlänge von 72 Zeichen.

Ob dein Code PEP‑8-konform ist, kannst du mit dem Python-Modul pylint prüfen. Damit lässt sich auch das Zeichenlimit für Kommentare und andere Codezeilen anpassen.

Schauen wir uns ein paar Beispiele an.

Beschreibung beim Importieren eines Moduls

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

Beschreibung einer Variablendefinition

n_classes = 10 # MNIST total classes (0-9 digits)

Für einen tieferen Einblick ins Kommentieren und typische Do&Don'ts schau dir diesen hilfreichen Beitrag an.

Als Nächstes lernst du, wie Docstrings bei der Dokumentation deines Codebestands helfen.

Docstrings zur Dokumentation von Python-Code

Ein Python-Docstring ist eine Dokumentationszeichenkette, die als Stringliteral direkt am Anfang einer Klasse, eines Moduls, einer Funktion oder Methode steht. Docstrings sind über das Attribut (__doc__) jedes Python-Objekts und über die eingebaute Funktion help() zugänglich.

Docstrings eignen sich hervorragend, um die Funktionalität größerer Codeeinheiten zu verstehen, also den generellen Zweck einer Klasse, eines Moduls oder einer Funktion. Kommentare hingegen beschreiben einzelne Codezeilen oder -ausdrücke und sind meist kurz. Sie sind vom Programmierenden vor allem für sich selbst und für Beitragende geschrieben. Gute Dokumentation unterstützt dich maßgeblich dabei, sauberen, gut verständlichen Code zu schreiben – ohne dass es dafür strikte Normen gibt.

Es gibt zwei Formen von Docstrings: einzeilige und mehrzeilige Docstrings. Beide werden von Data Scientists und Entwicklerinnen in Projekten genutzt.

Ein einzeiliger Docstring passt in eine Zeile. Du kannst einfache oder doppelte dreifache Anführungszeichen verwenden, Öffnen und Schließen müssen übereinstimmen. Bei einzeiligen Docstrings stehen die schließenden Anführungszeichen in derselben Zeile wie die öffnenden. Üblich ist die Verwendung von dreifachen doppelten Anführungszeichen.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

Mehrzeilige Docstrings enthalten dieselben Stringliterale wie einzeilige, werden jedoch durch eine Leerzeile von der ausführlicheren Beschreibung gefolgt.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Aus der obigen Übersicht wählen wir Pydoc als eines der Docstring-Formate und schauen es uns genauer an.

Wie du gelernt hast, sind Docstrings über das eingebaute Python-Attribut __doc__ und die Funktion help() zugänglich. Außerdem kannst du das eingebaute Modul Pydoc nutzen, das sich in seinen Funktionen deutlich vom doc-Attribut und der help-Funktion unterscheidet.

Pydoc ist praktisch, wenn du Code mit Kolleginnen teilst oder als Open Source veröffentlichst und damit eine größere Zielgruppe ansprichst. Es kann aus deiner Python-Dokumentation Webseiten generieren und sogar einen Webserver starten.

So funktioniert es.

Am einfachsten führst du Pydoc als Skript aus. In einer Jupyter-Lab-Zelle nutzt du dafür ein Ausrufezeichen (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Wie du siehst, zeigt Pydoc zunächst Textdokumentation zu Funktionen, Modulen, Klassen usw. an. Schauen wir, wie du das im Vergleich zur help-Funktion besser nutzt.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Jetzt rufen wir die glob-Doku mit der help-Funktion ab.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Wie du siehst, führt das zu einem NameError, weil glob nicht definiert ist. Du musst das Modul erst importieren, um help für die Dokumentation zu nutzen – bei Pydoc ist das nicht nötig.

Werfen wir einen Blick auf das spannendste Feature von Pydoc: Pydoc als Webservice starten.

Dafür startest du Pydoc als Skript mit dem Argument -b. Das startet einen HTTP-Server auf einem beliebigen freien Port und öffnet den Browser für die interaktive Dokuansicht. Das ist hilfreich, wenn bereits mehrere Dienste laufen und du nicht weißt, welcher Port frei ist.

!python -m pydoc -b

^C

Sobald du die Zelle ausführst, öffnet sich ein neues Fenster auf einem beliebigen Port. Der Browser sieht dann in etwa so aus:

Schauen wir uns die Dokumentation des Moduls h5py an. Es handelt sich um ein Dateiformat, das z. B. Gewichte von neuronalen Netzen speichert.

Wesentliches bei der Dokumentation von Python-Projekten

Unabhängig von Ziel, Vision und Zweck ähneln sich die Dokumentationen der meisten Projekte. Projekte lassen sich grob in folgende Kategorien einteilen:

Privates (persönliches) Projekt: Zum Portfolioaufbau oder als Freelancer mit GitHub-Repository.
Kollaborative (Team-)Projekte: Zum Beispiel ein Projekt in deiner Organisation oder eine Kaggle-Competition.
Open-Source-Projekte: Sie richten sich an ein breites Publikum. Zusammenarbeit, Beiträge und Wartbarkeit von Codebasis und Dokumentation stehen langfristig im Fokus.

Auch wenn die drei Kategorien unterschiedliche Ziele haben, kann eine gemeinsame Dokumentationsvorlage für alle funktionieren.

Angenommen, du arbeitest an einem Open-Source-Projekt und richtest dafür ein GitHub-Repository mit laufend aktualisierter, ausführlicher Doku ein. Diese Punkte sind essenziell:

Requirements-Datei: Häufig vergessen, aber sehr wichtig. Sie hilft Nutzerinnen, deinen Code schnell zu reproduzieren. Meist ist es eine Textdatei mit allen Paketen/Modulen samt Versionsangaben, die im Projekt genutzt wurden. Du kannst Requirements auch im Readme erwähnen, doch eine separate Datei ist besser – dann kann der oder die Nutzende sie einfach per pip installieren und alle Abhängigkeiten sind gesetzt.
Readme: Das Readme ist meist im Markdown-Format und das Rückgrat vieler Projekte. Es enthält eine Zusammenfassung, Features, Zweck und idealerweise ein Logo. Dort gehören Installations- und Nutzungshinweise hin. Ergänze außerdem wichtige Änderungen seit der letzten Version. Testskripte oder ein kurzer Quickstart, um den Code erfolgreich auszuführen, erhöhen das Vertrauen der Nutzenden. Weisen auch auf mögliche Stolpersteine hin.
Zusammenarbeit: Besonders wichtig bei Open Source. Erkläre, wie neue Beitragende mitmachen können: neue Features entwickeln, bekannte Bugs fixen, Doku ergänzen, neue Tests schreiben oder Issues melden. So kann die Community sogar eine v2.0 veröffentlichen und das Projekt voranbringen.
Lizenz: Eine Textdatei mit der verwendeten Lizenz, z. B. Boost, Apache, MIT usw. Gerade bei Open Source wichtig – sie klärt, ob und in welchem Umfang das Projekt kommerziell genutzt werden darf.
Aufgabenverteilung: In gemeinsamen Projekten (z. B. Kaggle) kannst du Aufgaben je Mitglied und deren Fortschritt dokumentieren. So behältst du den Überblick.
Framework-Wiederverwendung: In Teamprojekten entscheidend, damit andere Bausteine leicht wiederverwendet werden können und Zeit sparen – etwa eine Datenvorverarbeitungspipeline oder ein Skript für Cross-Validation.

Eine sehr empfehlenswerte, hervorragend strukturierte Dokumentation findest du im GitHub-Repository der huggingface-Transformers. Das ist ein Paradebeispiel dafür, wie ein Open-Source-Projekt aussehen kann.