Java-Grundlagen: Kommentare in Java richtig verwenden und javadoc Einführung

Der gekonnte Umgang mit Kommentaren ist ein essentieller Bestandteil des Programmierens.

Mit Kommentaren werden Klassen, Methoden, Berechnungen und Strukturen kurz beschrieben, so dass Betrachter des Quellcodes ein besseres Verständnis für die Funktion der Anwendung erlangen.

Java-Kommentare werden beim Kompilieren vom Compiler nicht beachtet und sind nur für die Programmierer von Bedeutung.

Gerade bei großen Softwareprojekten sind professionell verwendete Kommentare unverzichtbar.

Sie beschreiben das Zusammenspiel der Algorithmen und sorgen für Wiederverwendbarkeit des Quellcodes.

Die Anzahl und Länge von Kommentaren sollte wohl dosiert gewählt sein. Die Kommentare müssen auf den Punkt kommen, es dürfen dabei aber keine wesentlichen Informationen ausgelassen werden.

Bei der Fehlersuche in großen Programmen sorgen vergessene Kommentare nicht selten für vermeidbare Frustmomente. Daher gilt: Lieber ein Kommentar zu viel als einer zu wenig!

---

In Java unterscheidet man zwischen den folgenden 3 Kommentarenarten:

• Einzeilige Kommentare – Werden zeilenweise verwendet, sie beginnen mit einem Doppelschrägstrich // und enden mit dem Zeilenende.

• Blockkommentare – Werden für Erklärungen benutzt, die sich über mehrere Zeilen erstrecken. Sie beginnen mit einem Schrägstrich und Multiplikations-Zeichen /* und enden mit Multiplikations-Zeichen und Schrägstrich */.

• Dokumentationskommentare – Werden zu Dokumentationszwecken eingesetzt. Sie Sie beginnen mit einem Schrägstrich und zwei Multiplikations-Zeichen /** und enden mit Multiplikations-Zeichen und Schrägstrich */.

Während Zeilen- und Blockkommentare überall im Quellcode verwendet werden können und sollten, stehen Java-Dokumentationskommentare immer vor dem Element, welches sie beschreiben sollen.

Sie werden verwendet, um die Anwendungen direkt im Quelltext zu dokumentieren. Mit dem Werkzeug javadoc kann anschließend automatisch eine umfangreiche HTML-Dokumentation generiert werden.

Schauen wir uns die unterschiedlichen Java-Kommentararten und ihre Verwendung direkt im Quellcode anhand eines kleinen Beispielprogramms an:

Zeilen-, Block- und Dokumentationskommentare in Java.

import java.util.Scanner;

/**
 * Berechnet die Fläche eines Rechtecks.
 * Liest die Länge L und Breite B von der Kommandozeile ein
 * und gibt anschließend die Fläche F auf der Kommandozeile aus.
 * @author Kommandozeilenargumente werden ignoriert
 * @since JDK1.0
 * @see java.util.Scanner
 */
public class EingabeAusgabe {
    public static void main(String[] args) {

        // Deklaration der 3 Variablen für Länge, Breite und Fläche
        int L, B, F;

        Scanner eingabewert = new Scanner(System.in);

        Scanner eingabewert = new Scanner(System.in);
        System.out.print("Geben Sie die Laenge L ein (in cm): ");
        L = eingabewert.nextInt();
        System.out.print("Geben Sie die Breite B ein (in cm): ");
        B = eingabewert.nextInt();
        F = L * B;

        /*
        * Ausgabe der berechneten Fläche des Rechtecks.
        * Die Fläche wird in cm² auf der Kommandozeile ausgeben.
        */
        System.out.println("Die Flaeche des Rechtecks ist: " + F + " cm^2");
    }
}

Der obere Quelltext beginnt direkt mit einem Dokumentationskommentar, zu erkennen ist dies an den Zeichen /** ...... */. Mit Hilfe des Werkzeugs javadoc können diese Kommentare später zu einer speziellen HTML-Dokumentation zusammengesetzt werden.

In Zeile 14 sehen wir einen Zeilenkommentar, zu erkennen an den Zeichen //. Entwickler benutzen Zeilenkommentare oft für kurze Erklärungen und Notizen.

Am Ende des Quellcodes befindet sich ein vierzeiliger Blockkommentar, zu erkennen ist der Kommentar an den Zeichen /* ....... */. Blockkommentare können sich über beliebig viele Zeilen erstrecken und sind besonders für ausführliche Code-Beschreibungen geeignet.

Aus Java-Kommentaren mit Hilfe von javadoc eine HTML-Dokumentation generieren

Der Java-Dokumentationsgenerator javadoc ist seit Version 2 fester Bestandteil des JDKs. Mit Hilfe von javadoc kann aus Java-Quelltexten automatisch eine HTML-Dokumentation generiert werden, die später in einem Browser betrachtet werden kann.

Mittels speziellen Dokumentationskommentaren innerhalb des Java-Quelltextes werden detaillierte Beschreibungen zu den jeweiligen Klassen, Methoden, Felder und Interfaces vom Programmierer angegeben. Javadoc wertet den Quellcode aus und sucht dabei nach den Dokumentationskommentaren, zu erkennen an den Zeichen /* ....... */.

Anschließend erstellt javadoc aus den angegebenen Kommentaren zu jeder Klassendatei (z.B. MyClassA.java) eine HTML-Datei (z.B. MyClass.html) und fügt die einzelnen HTML-Dateien zu einer Gesamtdokumentation zusammen. Die Navigation in der so erstellten Java-Dokumentation wird durch zusätzliche Hilfs- und Indexseiten erleichtert, welche standardmäßig von javadoc erstellt werden.

Über spezielle javadoc-Tags, die mit dem Zeichen @ beginnen und am Anfang der Zeile stehen müssen, können Unterabschnitte detailliert beschrieben werden. In der unteren Tabelle werden die wichtigsten javadoc-Tags kurz vorgestellt und ihr Anwendungsgebiet genannt.

Mit Hilfe eines Doclets wird die HTML-Ausgabe schließlich von javadoc erstellt. Das Standard-Doclet generiert eine HTML-Dokumentation des eigenen Quellcodes.

Wenn andere Formate benötigt werden, können weitere Doclets benutzt werden. Dadurch kann die Dokumentation auch anstatt in HTML in den Formaten XML, PDF und RTF ausgegeben werden.

In den folgenden Abbildungen erfahrt ihr wie man mit javadoc eine HTML-Dokumentation für eine Java-Klasse erstellt. Zu Beginn befindet sich nur die Klassendatei EingabeAusgabe.java in dem Beispielsordner E:\java\Dokumentation (siehe Abbildung unten).

Mit dem Befehl javadoc EingabeAusgabe.java wird das Java-Dokumentationswerkzeug ausgeführt und beginnt mit dem Erstellen der HTML-Dokumentation. Über jeden einzelnen Arbeitsschritt wird mit einer kurzen Kommandozeilen-Ausgabe informiert. In der unteren Abbildung ist der Erstellungsprozess dargestellt:

Die generierten HTML-Dateien liegen in dem Ordner der Klassendatei. Die erstellte HTML-Dokumentation wird über die index.html aufgerufen, in der EingabeAusgabe.html befindet sich die Beschreibung der gleichnamigen Klasse. In den folgenden beiden Abbildungen sind die erstellten HTML-Dateien aufgelistet.

Die Klassendatei EingabeAusgabe.java ist ausgewählt, alle anderen Dateien wurden von javadoc erstellt und bilden die HTML-Dokumentation.

Die erstellte HTML-Dokumentation betrachtet man mit einem Browser. In der unteren Abbildung ist die Dokumentation der EingabeAusgabe-Klasse dargestellt. Im oberen Bereich kann man die Beschreibung der Klasse finden, zusammen mit den beiden Unterabschnitten Since und See Also, die wir über die javadoc-Tags @since und @see in dem Dokumentationskommentar angegeben haben.

---