Segment 02

briefings Code kommentieren: Do’s & Don’ts der Dokumentation

DATE 15/10/2025

TAGS DE

"Weniger ist mehr - aber nichts ist zu wenig." In diesem Kurzvortrag zeige ich, wie gute Code-Kommentare und Dokumentation aussehen können, ohne das Projekt unnötig aufzublähen. Wir sprechen über die "Do’s & Don’ts der Code-Dokumentation" und beantworten die wichtigsten Fragen: Was sollte im Code kommentiert werden - und was besser nicht? Wie schreibe ich verständliche Dokumentation für andere Entwickler, Tools und spätere Leser? Wer ist eigentlich verantwortlich fürs Dokumentieren - und wann? Anhand konkreter Beispiele aus der Praxis und einfachen "Rules of Thumb" bekommst du ein Gefühl dafür, wann Kommentare sinnvoll sind, wie du Funktionen besser verständlich machst, und welche Informationen außerhalb des Codes dokumentiert werden müssen. Der Fokus liegt auf Minimalismus mit Wirkung: So viel wie nötig, so wenig wie möglich - damit andere deinen Code verstehen, ohne dass du ihn ständig erklären musst.

Do’s & Don’ts der Dokumentation

„Weniger ist mehr - aber nichts ist zu wenig.“

15.10.2025

Warum Kommentare?

Code ist Kommunikation - mit Kollegen, Tools und dem Zukunfts-Ich
Kommentare erklären das Warum, nicht das Was
Gute Doku erspart Support, Fragen, Missverständnisse
(und erleichtert Benotungen 😉)

Das Ziel

Kommentar-Don’ts ❌

Redundante Kommentare
Offensichtliches kommentieren
Veraltete oder widersprüchliche Aussagen

// schlecht
int counter = 0; // Zähler auf 0 setzen

// schlechter
i = i + 1; // i wird um 1 erhöht

Bad Beispiel

Kommentar-Do’s ✅

Warum passiert etwas? - Motivation erklären
Workarounds, bekannte Bugs, technische Schulden
Hinweise für Wartung und Erweiterung

// gut
int counter = 0; // zählt fehlgeschlagene Verbindungsversuche

// besser
i++; // retry bei Timeout; wird im nächsten Release durch Exponential Backoff ersetzt

Verbessertes Beispiel

Funktion ohne Kommentar lesbar

Aber: Komplexität beachten!

Funktionsdokumentation

Python Beispiel

def calculate_checksum(data: bytes) -> int:
"""
Berechnet eine CRC32-Prüfsumme für gegebene Daten.
Args:
data (bytes): Eingabedaten als Byte-Array.
Returns:
int: CRC32-Prüfsumme als Integer.
"""
return zlib.crc32(data)

➡️ Klar, kurz, präzise - genug für spätere Nutzer.

➡️ API Idee - Doku reicht aus um Funktion zu verstehen.

Funktionsdokumentation

C++ Beispiel

/**

@brief Verbindet sich über COM-Port mit einem Gerät.

@param portName Name des Ports, z.B. “COM3”
@return true bei erfolgreicher Verbindung, false sonst
*/
bool connectToDevice(const std::string& portName);

➡️ Doxygen u.a. kann daraus automatisch HTML-Doku generieren.