Java-Kommentare

Kommentare sind Text, den der Compiler ignoriert. Sie existieren für die Menschen, die den Quellcode lesen. Java kennt drei Arten — einzeilige, mehrzeilige und Javadoc — jede mit ihrer eigenen Funktion.

Dieses Kapitel behandelt die Syntax aller drei Stile, wie man HTML-Dokumentation aus Javadoc generiert und — genauso wichtig — wann ein Kommentar es wert ist, geschrieben zu werden, und wann er nur Lärm erzeugt. Wenn Sie neu in der Java-Struktur sind, lesen Sie zuerst Java Syntax.

Einzeilige Kommentare — //

Alles von // bis zum Zeilenende ist ein Kommentar:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

Verwenden Sie diese für kurze Hinweise neben einer Codezeile oder um eine Zeile beim Debuggen vorübergehend zu deaktivieren.

Mehrzeilige Kommentare — /* ... */

Alles zwischen /* und */ wird ignoriert, auch über mehrere Zeilen hinweg:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Mehrzeilige Kommentare können auch inline erscheinen:

int width = 800 /* pixels */;

Sie können sie nicht verschachteln: /* outer /* inner */ */ endet beim ersten */, und die verbleibenden */-Zeichen verhindern die Kompilierung. Um einen Block auszukommentieren, der bereits /* … */ enthält, verwenden Sie // in jeder Zeile (Ihre IDE hat dafür eine Tastenkombination — üblicherweise Strg+/ / Cmd+/).

Javadoc-Kommentare — /** ... */

Javadoc-Kommentare beginnen mit /** (beachten Sie: zwei Sterne) und werden vom javadoc-Tool gelesen, um HTML-Dokumentation zu erzeugen:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Javadoc-Kommentare werden direkt oberhalb der Klasse, Methode oder des Feldes platziert, das sie beschreiben. Der erste Satz wird zur Zusammenfassungszeile in der generierten Dokumentation.

Die nützlichsten Tags:

• @param name description — eines pro Parameter
• @return description — was die Methode zurückgibt
• @throws ExceptionClass description — wann die Methode eine Ausnahme wirft
• @see ClassOrLink — Querverweise
• @since 1.5 — wann diese API hinzugefügt wurde
• @deprecated reason — rät von weiterer Verwendung ab (der Compiler warnt ebenfalls)

Die gesamte Standardbibliothek ist mit Javadoc dokumentiert; IDEs lesen sie, um ihre Tooltips zu befüllen.

Die HTML-Dokumentation generieren

Das javadoc-Tool wird mit dem JDK mitgeliefert. Zeigen Sie es auf Ihre Quelldateien (oder Pakete), und es erzeugt eine durchsuchbare HTML-Website:

javadoc -d docs Greeter.java

Das Flag -d docs wählt das Ausgabeverzeichnis. Öffnen Sie docs/index.html in einem Browser, um die generierten Seiten zu sehen — dasselbe Layout wie auf Oracles offizieller API-Dokumentation, erstellt aus den Kommentaren über jeder Klasse und Methode.

Wann kommentieren, wann nicht

Guter Code ist seine eigene Dokumentation. Kommentare, die nur wiederholen, was der Code bereits zeigt, erzeugen Lärm und veralten schnell:

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Kommentare rechtfertigen sich, wenn sie das Warum erklären, nicht das Was:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

Oder wenn sie eine nicht offensichtliche Einschränkung dokumentieren:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Für öffentliche APIs sollten Sie Javadoc schreiben. Für internen Code schreiben Sie nur die Kommentare, die dem nächsten Leser helfen, eine Entscheidung zu treffen.

Eine Demonstration

Der Compiler entfernt alle drei Kommentarstile, bevor er Bytecode generiert — sie haben daher null Laufzeitkosten.

Was kommt als Nächstes

Nachdem Sie nun Code dokumentieren können, fahren Sie mit den Grundbausteinen fort, die er beschreibt:

• Java Variables — Deklaration, Initialisierung und Geltungsbereich.
• Java Syntax — Anweisungen, Blöcke und die Regeln, die der Compiler durchsetzt.
• Java Hello World — das minimale Programm, in dem Ihre Kommentare leben.

Übungen