Softwaredokumentation#

Eine gute Dokumentation ist genauso wichtig wie der Code selbst – sie ermöglicht Wartung, Erweiterung und Übergabe von Software an andere Entwickler oder Anwender.

Arten der Dokumentation#

          Softwaredokumentation
                   │
      ┌────────────┼────────────┐
      ▼            ▼            ▼
Entwickler-    Anwender-    Technische
dokumentation  dokumentation  Dokumentation
(intern)       (extern)       (Architektur)

Entwicklerdokumentation (interne Dokumentation)#

Richtet sich an Entwickler, die den Code warten, erweitern oder debuggen müssen.

Code-Kommentare#

# Einzeiliger Kommentar – kurze Erklärung einer Zeile
x = x + 1  # Zähler erhöhen

"""
Mehrzeiliger Kommentar (Docstring):
Beschreibt eine Funktion oder Klasse ausführlich.
"""

def berechne_mehrwertsteuer(netto: float, steuersatz: float = 0.19) -> float:
    """
    Berechnet den Bruttobetrag inkl. Mehrwertsteuer.

    Parameter:
        netto (float):      Nettobetrag in Euro
        steuersatz (float): MwSt-Satz als Dezimalzahl (Standard: 0.19 = 19%)

    Rückgabe:
        float: Bruttobetrag in Euro

    Beispiel:
        >>> berechne_mehrwertsteuer(100)
        119.0
    """
    return netto * (1 + steuersatz)

Was gehört in einen guten Kommentar?#

Sinnvoll	Überflüssig
Warum etwas so gemacht wird	Was offensichtlich im Code steht
Erklärung komplexer Algorithmen	`x = x + 1 # x wird um 1 erhöht`
Dokumentation von Parametern/Rückgaben	Jede einzelne Zeile kommentieren
Bekannte Einschränkungen / TODO	Veraltete Kommentare (schlimmer als keine!)

Changelog / Versionierung#

Dokumentiert was wann von wem geändert wurde: