Softwaredokumentation

Mon, 01 Jan 0001 00:00:00 +0000

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: