Java-Kommentare: einzeilig, mehrzeilig und Javadoc

Wofür Kommentare da sind

Ein Kommentar ist Text in deinem Quellcode, den der Java-Compiler vollständig ignoriert. Er wird nie Teil des laufenden Programms - er existiert ausschließlich für die Menschen, die den Code lesen. Du verwendest Kommentare, um zu erklären, warum etwas auf eine bestimmte Weise gemacht wird, um Erinnerungen zu hinterlassen oder um Code vorübergehend zu deaktivieren, ohne ihn zu löschen.

Java kennt drei Arten von Kommentaren: einzeilige (//), mehrzeilige Blockkommentare (/* */) und Javadoc-Dokumentationskommentare (/** */). Sie erfüllen alle dieselbe grundlegende Aufgabe - sie werden beim Kompilieren ignoriert -, aber du greifst je nach Situation zu einem anderen.

Einzeilige Kommentare

Zwei Schrägstriche (//) beginnen einen Kommentar, der bis zum Ende der aktuellen Zeile reicht. Der Compiler überspringt alles vom // bis zum Zeilenumbruch.

public class Main {
    public static void main(String[] args) {
        // Eine Begrüßung in der Konsole ausgeben
        System.out.println("Hello, Java!");

        int score = 90; // ein Kommentar kann auch hinter dem Code stehen
        System.out.println(score);
    }
}

Beachte, dass der zweite Kommentar sich eine Zeile mit echtem Code teilt. Alles vor dem // läuft weiterhin; nur der Teil danach wird ignoriert. Das ist der häufigste Kommentarstil für kurze Notizen.

Mehrzeilige Blockkommentare

Wenn sich deine Notiz über mehrere Zeilen erstreckt, ist ein Blockkommentar sauberer, als jeder Zeile ein // voranzustellen. Ein Blockkommentar beginnt mit /* und endet mit */. Alles dazwischen - egal wie viele Zeilen - wird ignoriert.

public class Main {
    public static void main(String[] args) {
        /*
         * Dieses Programm zeigt einen Blockkommentar.
         * Die führenden Sternchen in jeder Zeile sind nur eine
         * Konvention zur besseren Lesbarkeit - sie sind nicht erforderlich.
         */
        System.out.println("Block comments are handy.");
    }
}

Die am linken Rand untereinander ausgerichteten *-Zeichen sind eine Stilkonvention, keine Regel. Die einzigen Teile, die wirklich zählen, sind das öffnende /* und das schließende */.

Code auskommentieren

Kommentare sind die übliche Methode, Code beim Experimentieren zu deaktivieren, ohne ihn zu löschen. Verwende // für eine einzelne Zeile oder einen Blockkommentar, um mehrere Zeilen auf einmal abzuschalten.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Führe es aus, und du wirst sehen, dass nur die beiden „runs"-Zeilen ausgegeben werden. Die auskommentierten println-Aufrufe sind für den Compiler unsichtbar.

Ein häufiger Stolperstein: Blockkommentare lassen sich nicht verschachteln. Das erste */ schließt den Kommentar, ganz gleich, wie viele /* davor standen. Du kannst also keinen /* ... */-Block in einen anderen /* ... */-Block einbetten - das innere */ beendet das Ganze, und der Rest wird zu einem Syntaxfehler. Wenn du einen Bereich deaktivieren musst, der bereits Blockkommentare enthält, verwende stattdessen // in jeder Zeile (die meisten Editoren erledigen das mit einem einzigen Tastenkürzel).

Javadoc-Dokumentationskommentare

Ein Javadoc-Kommentar sieht aus wie ein Blockkommentar, beginnt aber mit /** - zwei Sternchen. Er dient dazu, eine Klasse, eine Methode oder ein Feld zu dokumentieren, und steht direkt über dem, was er beschreibt. Das javadoc-Werkzeug verwandelt sie in durchsuchbare HTML-API-Dokumentation, und IDEs zeigen sie als Hover-Tooltips an.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Die Tags @param, @return und @throws sind strukturierte Felder, die das Werkzeug versteht. Für den Compiler ist das immer noch nur ein ignorierter Kommentar - sein Wert liegt vollständig in der Dokumentation, die er erzeugt, und in den Hinweisen, die die IDE anderen Entwicklern gibt (und dir selbst, sechs Monate später).

Gute Kommentare vs. Rauschen

Ein Kommentar sollte etwas erklären, das der Code nicht von sich aus sagen kann. Kommentare, die nur den Code wiederholen, schaffen Unordnung und neigen dazu, mit dem Code zu veralten.

// Schlecht: wiederholt nur, was der Code offensichtlich tut
int i = i + 1; // eins zu i addieren

// Besser: erklärt den Grund, den der Code nicht zeigen kann
retries++; // zurücknehmen und erneut versuchen; die API ist auf 5 Anf./Sek. begrenzt

Bemühe dich, den Code durch klare Namen und eine gute Struktur lesbar zu machen, und hebe dir Kommentare für das Warum auf: Absicht, Abwägungen, Sonderfälle und Verweise auf den Kontext. Wenn du dich dabei ertappst, einen Kommentar zu schreiben, um eine verwirrende Zeile zu erklären, ist das oft ein Hinweis, stattdessen eine Variable umzubenennen oder eine Methode auszulagern.

Weiter: Variablen

Jetzt, da du deinen Code mit Anmerkungen versehen kannst, ist der nächste Baustein das Speichern von Daten darin. Die nächste Seite behandelt Variablen - wie man sie deklariert, welche Typen sie aufnehmen und welche Regeln Java durchsetzt, weil es statisch typisiert ist.