Wie schreibe ich Kommentare?

In Java gibt es drei Arten von Kommentaren:

  • Zeilenkommentar: //
    Alles was in der selben Zeile hinter dem Kommentarzeichen steht, wird vom Compiler nicht übersetzt.
  • Blockkommentar: /* */
    Der Text der zwischen den Kommentarzeichen steht, wird vom Compiler ignoriert. Blockkommentare können nicht ineinander geschachtelt werden.
  • Javadoc-Kommentar: /** */
    Dieser Blockkommentar dient zum Dokumentieren von Klassen und Methoden. Diese Kommentare können zum automatisierten Generieren von Dokumentationen (Javadoc, Doxygen) verwendet werden.

Code sollte grundsätzlich so geschrieben sein, dass möglichst wenig Kommentare notwendig sind. Das kann durch passende Strukturierung, durch passende Namen für Pakete, Klassen, Methoden und Variablen erreicht werden.
Kommentare können Teil der Dokumentation sein (Javadoc). Sie sollen das Lesen des Codes für andere erleichtern. Bei Änderungen im Code sollte man nicht vergessen, die Kommentare an die Veränderungen anzupassen.

Beispiel für Javadoc-Kommentare in der Klasse String aus der Java-Klassenbibliothek:

/**
 * Returns the length of this string.
 * The length is equal to the number of <a href="Character.html#unicode">Unicode
 * code units</a> in the string.
 *
 * @return  the length of the sequence of characters represented by this
 *          object.
 */
public int length() {
    return value.length;
}

/**
 * Returns {@code true} if, and only if, {@link #length()} is {@code 0}.
 *
 * @return {@code true} if {@link #length()} is {@code 0}, otherwise
 * {@code false}
 *
 * @since 1.6
 */
public boolean isEmpty() {
    return value.length == 0;
}
de German
X