26.3 Quellcode kommentieren

Jede Datei, die Quelltext in irgendeiner Form enthält, muss dokumentiert werden. Aus einigen einleitenden Zeilen muss deutlich werden, was der Quelltext macht. Daneben sollten auch Copyright-Informationen Platz finden. Kommentare in den öffentlichen Klassen müssen so verfasst sein, dass diejenigen, die die Klassen auch benutzen, etwas damit anfangen können. Somit hat die Dokumentation der Funktionalität eine ganz andere Qualität als die Dokumentation des Quelltexts, die in erster Linie für die Programmierer interessant ist.

26.3.1 Kommentartypen

In Java gibt es drei Möglichkeiten für Kommentare:

Zeilenkommentare mit //

Blockkommentare mit /* */

Besondere Blockkommentare, die JavaDoc-Kommentare mit /** */

Ebenso wie einleitende Worte jede Datei beschreiben, geht die Dokumentation in der benutzten Klasse und den Funktionen weiter. Nach dem oberen Block, welcher die Datei als Ganzes beschreibt, folgen in der Regel die Definition des Pakets, dann die Import-Klauseln und anschließend die Deklaration der implementierten Klassen.

Alle Kommentare und Bemerkungen sollten in Englisch verfasst werden, um Projektmitgliedern aus anderen Ländern das Lesen zu vereinfachen. Für allgemeine Kommentare sollten wir die Zeichen // benutzen. Sie haben zwei Vorteile:

Bei Editoren, die Kommentare nicht farblich hervorheben - oder bei einer einfachen Quellcodeausgabe auf der Kommandozeile - lässt sich ersehen, dass eine Zeile, die mit // beginnt, ein Kommentar ist. Einen Quelltext zu übersehen, der für mehrere Seiten mit den Kommentarzeichen /* und */ unterbrochen wird, ist schwierig. Zeilenkommentare machen deutlich, wo Kommentare beginnen und wo sie enden.

Der Einsatz der Zeilenkommentare eignet sich besser dazu, während der Entwicklungs- und Debug-Phase Codeblöcke auszukommentieren. Benutzen wir zur Programmdokumentation die Blockkommentare, so sind wir eingeschränkt, denn Kommentare dieser Form können wir nicht schachteln. Zeilenkommentare können einfacher geschachtelt werden.

Ein weiterer Vorteil ist, dass Editoren Tastaturkürzel zum Kommentieren und Auskommentieren mitbringen. Bei Eclipse ist das etwa (Strg)+(/) und (Strg)+(\).

26.3.2 Strategischer und taktischer Kommentar

Quellcode muss kommentiert werden. Die Kommentare sollten einfach zu finden und in natürlicher Sprache verfasst sein. Sind die Bezeichnernamen gut gewählt, so ist auch weniger an Quelltext zu kommentieren. Programmieren wir über eine längere Zeit, so müssen wir auch angeben, wann wir mit der Implementierung begonnen haben und wann wir Änderungen durchführen. Gerade deshalb ist es wichtig, mit JavaDoc zu arbeiten, denn die Dynamik eines Programms wird festgehalten und die externe Dokumentation ist immer aktuell. Kommentare können strategisch oder taktisch sein.

Sicherlich ist nicht sofort ersichtlich, was eine Zeile wie j = i-- + ++i + i++ - --i so alles leistet. Vorsicht ist allemal gegeben, denn viele taktische Kommentare machen den Programmtext unleserlich. Wir sollten daher versuchen, viele Informationen im strategischen Kommentarblock unterzubringen und nur wirklich wichtige Stellen mit taktischen Kommentaren zu markieren. Der folgende Ausschnitt gibt Einblick in die Klasse BigInteger. Die Klasse gehört seit Java 1.1 zum API-Standard:

// Arithmetic Operations
/**
* Returns a BigInteger whose value is (this + val).
*/
public BigInteger add(BigInteger val) throws ArithmeticException {
if (val.signum == 0)
    return this;
else if (this.signum == 0)
    return val;
else if (val.signum == signum)
    return new BigInteger(plumbAdd(magnitude, val.magnitude),
                       signum);
else if (this.signum < 0)
    return plumbSubtract(val.magnitude, magnitude);
else  /* val.signum < 0 */
    return plumbSubtract(magnitude, val.magnitude);
}

Die gesamte Klasse zerfällt in mehrere Teile, wobei der obere Teil ein Auszug der arithmetischen Operationen ist. Die Gliederung der Datei in die verschiedenen Ebenen besteht natürlich nur im Quelltext, und Sun wählte, um dies deutlich zu machen, die Zeilenkommentare. Alles, was also mit // beginnt, gliedert den Quelltext. Das heißt aber auch, dass normale, also taktische Kommentare, mit den herkömmlichen Zeichen abgegrenzt werden.

else                      // val.signum < 0

Dieser Kommentar ist besonders gut, und wir kommen später noch einmal darauf zu sprechen, denn er erklärt den else-Teil der Fallunterscheidung. Auf den ersten Blick ist also zu sehen, wann dieses Codesegment ausgeführt wird.

26.3.3 Bemerkungen über JavaDoc

JavaDoc erstellt aus den strategischen Kommentarzeilen

/**
 * Returns a BigInteger whose value is (this + val).
 */
 public BigInteger add(BigInteger val) throws ArithmeticException {

eine HTML-Datei, die Anwendern der Klasse einen Überblick über den Prototyp der Funktion gibt. Wir sehen sofort: Die Funktion ist public, sie trägt den Namen add, erlaubt einen Übergabeparameter vom Objekttyp BigInteger und gibt auch, wenn sie nicht gerade eine ArithmeticException auslöst, ein BigInteger zurück.

Es ist sehr nützlich, in die Kommentare HTML-Code einzubetten. Die gewöhnlichen HTML-Kommandos sind dabei zugelassen - Näheres dazu findet sich im vorhergehenden Kapitel über JavaDoc. Ein anderes Beispiel macht den Einsatz von DocComments mit HTML-Tags noch deutlicher und soll noch einmal eine gut kommentierte Klasse zeigen. Es handelt sich diesmal um die Klasse InetAddress:

/**
 * This class represents an Internet Protocol (IP) address.
 * <p>
 * Applications should use the methods getLocalHost,
 * getByName, or getAllByName to
 * create a new InetAddress instance.
 *
 * @author  Chris Warth
 * @version 1.42, 02/23/97
 * @see     java.net.InetAddress#getAllByName(java.lang.String)
 * @see     java.net.InetAddress#getByName(java.lang.String)
 * @see     java.net.InetAddress#getLocalHost()
 * @since   JDK1.0
 */
public final
class InetAddress implements java.io.Serializable {
   ...
}

26.3.4 Gotcha-Schlüsselwörter

Besondere Eigenschaften eines Quelltexts müssen hervorgehoben werden. Dazu dienen Kommentare, die aber in verschiedenster Form vorkommen. Es ist dabei nur von Vorteil, wenn die Kommentare in Kategorien eingeteilt werden: Diese Programmstelle ist besonders trickreich, die andere beschreibt eine mögliche Fehlerquelle und so weiter. Wir wollen spezielle Kommentarmarkierungen (Gotcha-Schlüsselwörter) verwenden, die später von Programmen weiterverarbeitet werden. So könnte ein kleines Shell-Skript schnell spezielle Schlüsselwörter heraussuchen und in einer Liste zusammenfassen. Diese Liste kann dann zur Nachbearbeitung nützlich sein.

Tabelle 26.1 Gotcha-Schlüsselwörter und ihre Bedeutung

Die einzelnen Symbole sollten die ersten im Kommentar sein; anschließend sollte eine Zeile kurz das Problem erläutern. Bei der Entwicklung im Team sollten die Programmierer die von ihnen gemachten Anmerkungen durch ein Namenskürzel kenntlich machen. Ebenso ist das Datum zu vermerken (nach einer Zeit können Bemerkungen entfernt werden) und jeder, der den Quelltext geändert hat. So lässt sich insbesondere die Behebung von Fehlern dokumentieren.

// :TODO: ulliull 970702: give the program the last kick

<Eclipse: »Eclipse kennt zum Beispiel das Gotcha TODO:. Taucht es im Quellcode auf, so visualisiert Eclipse dies mit einem eigenen Symbol, was links neben dem Quellcode angezeigt wird.« >

Versionskontrollen-Verwaltungsprogramme wie CVS (Concurrent Versions System) erlauben ebenfalls nachzuvollziehen, welcher Autor wann eine Änderung vorgenommen hat.