Antwort.

Hintergrund

In Python wird seit den frühesten Versionen die Dokumentation von Code über Docstrings gefördert. Mit der Einführung von Python 3.5 (PEP 484) wurden Typannotationen (Type Hints) hinzugefügt, um die Lesbarkeit zu verbessern und die Unterstützung von Typanalysatoren (wie mypy, pyright usw.) zu optimieren. Auf diese Weise kann man Dokumentation und Typisierung direkt in der Definition von Funktionen und Klassen kombinieren.

Problem

Ohne Typannotationen ist es schwierig, schnell zu verstehen, womit eine Funktion arbeitet und was man von ihr erwarten kann. Ein Mangel an guten Docstrings führt zu Missverständnissen in der Schnittstelle und zu Fehlern bei der Benutzung. Wenn Typ-Hinweise oder Docstrings falsch verwendet werden, beeinflusst dies die statische Analyse und verschlechtert die Unterstützung des Codes.

Lösung

Mehrzeilige Docstrings verwenden, um den Zweck der Funktion, ihre Parameter und das Ergebnis zu dokumentieren, sowie Typ-Hinweise für die explizite Angabe der Typen von Argumenten und Rückgabewerten.

Beispielcode:

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

    :param a: Erste Summand, int
    :param b: Zweite Summand, int
    :return: Summe, int
    """
    return a + b

Wesentliche Merkmale:

Docstring wird in doc gespeichert und ist für IDEs, help(), und automatische Dokumentationsgeneratoren zugänglich
Typannotationen sind über annotations verfügbar; sie beeinflussen die Ausführung des Codes nicht, sondern dienen nur der Analyse
Die kombinierte Anwendung erleichtert die umfangreiche Unterstützung und das Onboarding neuer Programmierer

Trickfragen.

Können Typannotationen die Ausführung des Programms beeinflussen?

Nein. Typannotationen (Type Hints) werden vom Python-Interpreter zur Laufzeit nicht überprüft und dienen ausschließlich für Analysatoren und IDEs sowie zur automatischen Dokumentationserstellung. Sie führen nicht zu Laufzeitfehlern und sind immer optional.

Kann man Typannotationen verwenden, um Werte für Parameter einzuschränken?

Nein. Die Angabe eines Typs, z.B. x: int, verhindert nicht, dass Werte eines anderen Typs übergeben werden. Dafür kann man Laufzeitprüfungen (assert/isinstance) verwenden, jedoch keine Typ-Hinweise — sie werden nicht automatisch verifiziert.

Kann man Kommentare # type: ... anstelle von Annotations verwenden? Wofür ist das notwendig?

Ja, das ist erlaubt, wenn Kompatibilität mit Python 2 oder alten Codebasen benötigt wird. Zum Beispiel:

def foo(x, y):     # type: (int, str) -> bool
    pass

Das verstehen mypy und ähnliche Werkzeuge genauso wie die moderne Syntax, aber in neuen Projekten ist es besser, die Standardannotationen zu verwenden.

Typische Fehler und Anti-Patterns

Fehlende Docstrings oder leere Docstrings bei öffentlichen Funktionen und Klassen
Falsche Typangaben – z.B. List anstelle von list oder Tippfehler in den Typen (insbesondere bei komplexen Sammlungen)
Verwendung von Typ-Hinweisen ohne Aktualisierung der Dokumentation und umgekehrt

Beispiel aus der Praxis

Negativer Fall

In einem großen Projekt sind Funktionen überhaupt nicht mit Docstrings und Typ-Hinweisen versehen – der Entwickler benötigt viel Zeit für das Studium und Debugging, macht häufig Fehler bei den Typen und dem Zweck der Eingabedaten.

Vorteile:

Schnelles Schreiben von Code zu Beginn

Nachteile:

Große Schwierigkeiten bei der Wartung, das Onboarding neuer Mitarbeiter dauert lange
Fehler sind schwer zu identifizieren, wenn die Typen der Parameter verwechselt werden

Positiver Fall

In allen öffentlichen Funktionen sind ausführliche Docstrings und korrekte Typ-Hinweise vorhanden, was es IDEs und Analysatoren ermöglicht, Typfehler schnell zu finden und automatisch Dokumentation für die API zu erstellen.