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

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

refactoring

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

python_comment_3

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

python_comment

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.

Auto-generierte Dokumentation

Pros:

  • Automatisierung, HTML-Ausgabe, CI/CD-kompatibel
  • Guter Einstiegspunkt für neue Teammitglieder

Con:

  • Nützlichkeit hängt vom Inhalt der Kommentare ab
  • „Autogeneriert“ heißt nicht „automatisch gut“
  • Nur Code Dokumentation reicht nicht (README, Intro, Installation…)

Wer ist verantwortlich?

  • Jede:r im Team, nicht nur Architekt:in oder Doku-Team
  • Kommentare entstehen während der Implementierung
  • Code Reviews: Doku ist Teil der Review-Kriterien!
  • Clean Code ≠ kommentarfreier Code
  • Comment Garden Prinzip

Rules of Thumb

  • KISS - Keep it simple stupid
  • DRY - Don’t repeat yourself
  • Code ist Teamwork

Takeaways

  • Kommentiere Warum, nicht Was
  • Schreibe für Menschen, nicht für Compiler
  • Regel: So viel wie nötig, so wenig wie möglich
  • Nutze Tools sinnvoll - kein Selbstzweck!

END OF BRIEFING

QR code for https://wieerwill.dev/vcard.vcf

MAIL:
robert.jeutter@wieerwill.dev

MASTODON:
https://chaos.social/@wieerwill

LINKEDIN:
https://www.linkedin.com/in/wieerwill

WEB:
https://wieerwill.dev