Code-Dokumentation: JavaDoc, Docstrings, OpenAPI

Code wird mehr gelesen als geschrieben (vgl. L5). Gute Dokumentation macht den Unterschied zwischen „in 2 Stunden produktiv" und „in 2 Wochen verirrt". Aber: Dokumentation kann auch schlechter sein als gar keine – nämlich wenn sie veraltet ist.

Diese Lektion zeigt drei Doku-Welten: Inline-Code-Dokumentation (JavaDoc, Docstrings, JSDoc) für Funktionen und Klassen, API-Dokumentation (OpenAPI/Swagger) für REST-Schnittstellen und Projekt-Dokumentation (README, ARCHITECTURE.md) für das Big Picture. Plus: was ist gute vs. schlechte Doku?

1) Die Dokumentations-Pyramide

Wie bei Tests gibt es auch bei Doku verschiedene Ebenen. Von Detail zu Big-Picture:

Doku-Ebenen vom Detail zum Big Picture

Wer eine fremde Codebase betritt, startet typisch am README: was ist das, wie startet es, wofür ist es da? Dann tiefer rein zur Architektur und schließlich zu konkreten Funktionen. Eine gut dokumentierte Codebase ermöglicht das. Eine schlechte zwingt zum Reverse-Engineering durch Code-Lesen.

2) Inline-Code-Doku-Formate je Sprache

Fast jede Sprache hat ein etabliertes Format für Funktions-Dokumentation. Klick durch:

Code-Doku-Formate in vier Sprachen

Java – JavaDoc

/** * Berechnet den Rabatt für einen Kundenpreis. * * <p>Senioren ab 65 erhalten 30 %, Kinder unter 18 * erhalten 50 %, sonst kein Rabatt.</p> * * @param betrag Originalpreis in Euro, > 0 * @param alter Alter des Kunden in Jahren * @return rabattierter Preis * @throws IllegalArgumentException wenn betrag <= 0 * @since 1.2.0 */ public double berechneRabatt(double betrag, int alter) { if (betrag <= 0) { throw new IllegalArgumentException("Betrag muss positiv sein"); } if (alter < 18) return betrag * 0.5; if (alter >= 65) return betrag * 0.7; return betrag; }

Beachte: Doku gehört direkt in den Code, nicht in eine externe Datei. Vorteil: bei Code-Änderungen wird die Doku im selben Commit angepasst. Nachteil: Doku-Schreiben fühlt sich an wie Mehrarbeit – muss disziplinär durchgezogen werden. Aus den Inline-Kommentaren generieren Tools (siehe nächste Sektion) dann HTML-Dokumentation.

3) Wichtige Tags in JavaDoc & Co.

Die meisten Doku-Formate kennen ähnliche Tags. Hier eine Übersicht:

Standard-Tags der Code-Doku-Formate

Tag	Bedeutung	Beispiel
@param	Beschreibt einen Parameter.	`@param alter Alter in Jahren`
@return	Beschreibt den Rückgabewert.	`@return rabattierter Preis`
@throws	Welche Exception kann fliegen?	`@throws NullPointerException`
@deprecated	Markiert als veraltet.	`@deprecated nutze stattdessen X()`
@since	Ab welcher Version verfügbar.	`@since 1.2.0`
@see	Verweis auf andere Doku.	`@see Customer#getName()`
@author	Autor (selten genutzt heute).	`@author A. Müller`
@example	Beispiel-Aufruf (JSDoc).	`@example calc(10, 20)`

Tools wie JavaDoc (Java), Sphinx (Python), TypeDoc/JSDoc (TS), Doxygen (C/C++) generieren aus den Kommentaren HTML-Doku-Seiten. Die Standard-Bibliotheken aller Sprachen sind so dokumentiert (siehe z.B. Java-Docs).

4) OpenAPI / Swagger – die API-Doku-Welt

Wenn dein Code eine REST-API anbietet, brauchst du eine eigene Doku-Welt: OpenAPI (vorher „Swagger"). Eine YAML- oder JSON-Datei beschreibt deine API – aus ihr lassen sich generieren: Doku-Webseiten, Client-Bibliotheken, Mock-Server, Test-Suites.

OpenAPI 3.x – Beispiel für einen Endpoint

api.yaml

openapi: 3.0.3 info: title: Bestell-API version: 1.2.0 description: Verwaltet Bestellungen im Shop-System paths: /bestellungen/{id}: get: summary: Holt eine Bestellung parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Bestellung gefunden content: application/json: schema: $ref: '#/components/schemas/Bestellung' '404': description: Nicht gefunden

Aus dieser einen Datei lassen sich generieren: interaktive HTML-Doku (z.B. Swagger UI, Redoc), Client-SDKs (in 30+ Sprachen!), Mock-Server für Frontend-Entwicklung, automatische Validierung in Request/Response. Tools: Swagger UI, Redoc, Postman (importiert OpenAPI). Vertieft in K51 L9.

5) Doku-Tools je Sprache

JavaDoc: mvn javadoc:javadoc generiert HTML-Doku.
Sphinx (Python): generiert mächtige HTML-Doku, Standard für Bibliotheken wie Django, NumPy.
TypeDoc / JSDoc: für TypeScript / JavaScript.
Doxygen: der C/C++-Klassiker, unterstützt aber auch viele andere Sprachen.
MkDocs: für Markdown-basierte Projekt-Doku.
Docusaurus / VitePress: moderne Doku-Sites mit Versionierung und Suche.
Swagger UI / Redoc: für OpenAPI-basierte API-Doku.
Read the Docs: Hosting-Plattform speziell für technische Doku.

6) README – die erste Visitenkarte

Die README.md ist das Erste, was jeder Besucher eines Repos sieht. Sie entscheidet, ob jemand das Projekt verstehen oder weiterklicken wird. Eine gute README hat:

Standard-Sektionen einer guten README

Titel + Tagline

Projektname und ein Satz, was es macht.

Status / Badges

Build-Status, Coverage, Version, Lizenz.

Features

Was kann das Tool? Stichpunktliste.

Installation

Genaue Schritte. Copy-paste-fähig.

Quickstart

Hello-World-Beispiel in 3-5 Zeilen.

Verwendung

Häufige Use Cases mit Code.

Konfiguration

Welche Env-Variablen, welche Config-Files?

Contributing

Wie man Beiträge einreicht (oft separates CONTRIBUTING.md).

Lizenz

Welche Lizenz? Vgl. L4.

Faustregel: Wer das README liest, soll in 5 Minuten verstehen, was das Projekt tut und ob es für ihn relevant ist. Zu viel Doku ist genauso schlecht wie zu wenig – Fokus auf das, was Erstbesucher brauchen. Tiefere Details in separate Dokumente.

7) Architektur-Dokumentation

Bei größeren Projekten reicht README nicht. Eine ARCHITECTURE.md oder ähnlich erklärt die Strukturentscheidungen:

Komponenten / Module: wie ist das System geschnitten?
Datenfluss: wer ruft wen auf? Welche Daten gehen wohin?
Externe Abhängigkeiten: welche Datenbank, welche APIs, welche Services?
Diagramme: UML, Sequence-Diagrams (vgl. K50 L4).

Populär: C4-Model (Context, Container, Component, Code) – vier Zoom-Stufen vom System-Überblick bis zur Code-Ebene. Tool dafür: Structurizr.

8) ADRs – Architecture Decision Records

Eine clevere Idee aus der Praxis: ADRs dokumentieren warum bestimmte Architektur-Entscheidungen getroffen wurden. Format ist simpel:

Titel: kurze Beschreibung der Entscheidung.
Status: proposed / accepted / superseded.
Kontext: warum stand die Entscheidung an?
Entscheidung: was wurde entschieden?
Konsequenzen: was bedeutet das für die Zukunft?

ADRs werden ins Repo committed (z.B. unter docs/adrs/0001-database-choice.md) und nie geändert – wenn eine Entscheidung überholt ist, kommt ein neues ADR und das alte wird auf „superseded" gesetzt. So wird das Erbe der Architektur-Entscheidungen sichtbar.

9) Gute vs. schlechte Doku

Anti-Patterns und Gegenbeispiele

✗ Was statt Warum

// erhöht i um 1 ist nutzlos – sagt nur was der Code tut. Warum erhöhen wir?

✓ Warum erklären

// Skip first row (header) erklärt die Absicht, nicht die Mechanik.

✗ Veraltete Kommentare

Schlimmer als gar keine: Code wurde geändert, Kommentar nicht. Verwirrt.

✓ Doku im selben Commit

Code-Änderung und Doku-Update in einem Commit. Bei PR-Reviews mitkontrollieren.

✗ Schreibroman

5-Absatz-Kommentar über eine 3-Zeilen-Funktion. Liest niemand.

✓ Knapp und präzise

1-3 Sätze für die Funktion, mehr wenn nötig. Sprache präzise wählen.

✗ Auskommentierter Code

Wer aufhebt was nicht mehr da ist – Git hat die Historie. Weg damit.

✓ git log statt Kommentar

Wenn du wissen willst, was vorher war: git blame und git log.

10) Documentation-as-Code

Ein moderner Trend: Doku wird wie Code behandelt – im selben Repo, mit Versionierung, Pull Requests, Reviews. Vorteile:

Synchronisation: Code-Änderung und Doku-Änderung im selben PR.
Versionierung: Doku zu v1.0 unterscheidet sich von v2.0. Git macht das.
Reviews: Doku-Änderungen werden wie Code reviewt.
Tooling: Linter auch für Doku (Spell-Check, Markdownlint, Vale).
CI-Integration: Doku wird automatisch deployed.

Klassische Tools: MkDocs, Docusaurus, VitePress, Sphinx. Hosting: GitHub Pages, Read the Docs, Netlify.

Zusammenfassung

Doku-Pyramide: Inline-Kommentare → Funktions-Doku → API-Doku → Architektur → README. Code-Doku: JavaDoc (Java, /** */), Docstrings (Python, """..."""), JSDoc (JS/TS), XML-Doc (C#). Standard-Tags: @param, @return, @throws, @deprecated. API-Doku: OpenAPI/Swagger (YAML), generiert Swagger UI + Client-SDKs. README: Titel, Install, Quickstart, Verwendung, Konfig. ADRs für Architektur-Entscheidungen. Documentation-as-Code: Doku im Repo, mit PRs, in CI deployed. Anti-Patterns: was statt warum, veraltet, Schreibroman, auskommentierter Code. Nächste Lektion: Statische Codeanalyse mit SonarQube.