Java Kommentare & Javadoc: Code sauber dokumentieren

Stell dir vor, du schaust dir drei Monate später deinen eigenen Code an - und hast keine Ahnung mehr, was du da eigentlich gemacht hast. Genau dieses Problem lösen Java Kommentare und Javadoc. Kommentare sind Textstellen im Quellcode, die der Compiler (das Programm, das deinen Code in ausführbaren Maschinencode übersetzt) ignoriert. Javadoc ist ein spezielles Format, um aus Kommentaren automatisch professionelle HTML-Dokumentation zu generieren.

Als Azubi, Student oder Berufseinsteiger unterschätzt man Kommentare oft. Man denkt, der Code spricht für sich. Spoiler: Tut er nicht. Und in deinem ersten richtigen Projekt wird dein Team-Lead erwarten, dass du sauber dokumentierst. Hier erfährst du, wie das richtig funktioniert.

Was sind die drei Arten von Java-Kommentaren?

Java unterscheidet grundsätzlich drei Arten von Kommentaren: Einzeilige Kommentare, mehrzeilige Kommentare und Javadoc-Kommentare. Jede Art hat ihren spezifischen Einsatzzweck, den du kennen solltest. Eine Übersicht findest du auch bei W3Schools.

Definition: Kommentare in Java sind Anmerkungen im Quellcode, die nicht vom Compiler ausgeführt werden. Sie dienen der Dokumentation und Erklärung für menschliche Leser.

Einzeilige Kommentare mit //

Einzeilige Kommentare beginnen mit zwei Schrägstrichen (`//`). Alles, was nach diesen Zeichen in derselben Zeile steht, wird vom Java-Compiler übersprungen.

int alter = 25; // Das Alter der Person in Jahren

// Die naechste Zeile berechnet das Geburtsjahr basierend auf dem aktuellen Jahr
int geburtsjahr = 2024 - alter;

Nutze einzeilige Kommentare für kurze Erklärungen direkt neben einer Code-Zeile. Warum? Weil sie schnell geschrieben sind und den Lesefluss nicht stören. Sie sind perfekt, um kurz zu erklären, warum eine Zeile so ist, wie sie ist.

Mehrzeilige Kommentare mit /* */

Mehrzeilige Kommentare beginnen mit `/*` und enden mit `*/`. Alles, was zwischen diesen Markierungen steht, gilt als Kommentar. Das ist nützlich für längere Beschreibungen oder das temporäre Auskommentieren von Code-Blöcken während der Entwicklung.

/*
 * Diese Methode berechnet den Endpreis.
 * Der Preis beinhaltet den Rabatt und die Mehrwertsteuer.
 * Parameter: grundpreis, rabattInProzent
 */
public double berechneEndpreis(double grundpreis, int rabattInProzent) {
  double rabatt = (grundpreis * rabattInProzent) / 100;
  double netto = grundpreis - rabatt;
  return netto * 1.19; // 19% MwSt hinzufuegen
}

Javadoc-Kommentare mit /** */

Javadoc ist das Standardwerkzeug in der Java-Welt. Es wandelt speziell formatierte Kommentare in eine lesbare HTML-Webseite um. Diese Kommentare beginnen immer mit einem Schrägstrich und zwei Sternchen (`/**`) und enden mit `*/`.

/**
 * Berechnet den Endpreis inklusive Rabatt und Mehrwertsteuer.
 * Diese Methode wird verwendet, um Preise im Warenkorb zu aktualisieren.
 *
 * @param grundpreis      Der Preis vor Rabatt und Steuern
 * @param rabattInProzent Rabatt als ganzzahliger Prozentwert (0-100)
 * @return Den finalen Endpreis inklusive 19% Mehrwertsteuer
 */
public double berechneEndpreis(double grundpreis, int rabattInProzent) {
  double rabatt = (grundpreis * rabattInProzent) / 100;
  double netto = grundpreis - rabatt;
  return netto * 1.19;
}

Wichtig: Javadoc wird zwingend mit `/**` (drei Sternchen am Anfang) eingeleitet. Nur so erkennt das Tool den Kommentar als Teil der öffentlichen API-Dokumentation.

Wann nutzt du welche Kommentarart?

Die Wahl der richtigen Kommentarart ist essenziell für sauberen Code. Eine klare Unterscheidung hilft dir und anderen, sich schneller zurechtzufinden.

Stell dir Kommentare wie verschiedene Kommunikationsmittel vor: Einzeilige Kommentare sind ein kurzer Zuruf an einen Kollegen. Mehrzeilige Kommentare sind eine E-Mail. Und Javadoc ist das offizielle Handbuch, das jeder im Team lesen muss, um dein Tool zu benutzen.

Was sind die wichtigsten Javadoc-Tags?

Javadoc-Tags sind spezielle Befehle, die mit einem `@` beginnen. Sie geben dem Dokumentations-Tool Anweisungen zur Formatierung. Ohne diese Tags wäre die generierte HTML-Seite nur unstrukturierter Text.

Hier sind die Tags, die du als Einsteiger am häufigsten verwenden wirst:

Eine vollständige Liste aller Tags findest du in der offiziellen Oracle Javadoc Dokumentation.

Wie wendet man Javadoc in der Praxis an?

Theorie ist gut, Praxis ist besser. Hier siehst du eine komplett dokumentierte Klasse. Das ist der Qualitätsstandard, den du in Projekten anstreben solltest. Beachte besonders die fehlenden Umlaute in den Strings, um Encoding-Probleme zu vermeiden.

/**
  * Repraesentiert einen Artikel im Onlineshop.
  * Die Klasse speichert Basisinformationen wie Namen und Preis.
  *
  * @author Max Mueller
  * @version 1.0
  * @since 2024-01-01
  */
public class Artikel {

    /** Der Name des Artikels. Darf nicht null sein. */
    private String name;

    /** Der Bruttopreis in Euro. Muss groesser als 0 sein. */
    private double preis;

    /**
      * Erzeugt einen neuen Artikel mit Namen und Preis.
      *
      * @param name  Der Artikelname (darf nicht null sein)
      * @param preis Der Bruttopreis in Euro (muss positiv sein)
      * @throws IllegalArgumentException wenn name null oder preis negativ ist
      */
    public Artikel(String name, double preis) {
        if (name == null) {
            throw new IllegalArgumentException("Name darf nicht null sein");
        }
        if (preis < 0) {
            throw new IllegalArgumentException("Preis muss positiv sein");
        }
        this.name = name;
        this.preis = preis;
    }

    /**
      * Berechnet den Preis nach Abzug des Rabatts.
      *
      * @param rabattInProzent Rabatt als Prozentwert (0-100)
      * @return Der reduzierte Preis in Euro
      * @see getName()
      */
    public double getPreisMitRabatt(int rabattInProzent) {
        return preis * (100 - rabattInProzent) / 100.0;
    }

    /**
      * Gibt den Artikelnamen zurueck.
      *
      * @return Der aktuelle Name des Artikels als String
      */
    public String getName() {
        return name;
    }
}

Um aus diesem Code die Dokumentation zu erzeugen, öffnest du dein Terminal (Kommandozeile) und gibst folgenden Befehl ein:

javadoc -d doc Artikel.java

Der Parameter `-d doc` sorgt dafür, dass alle HTML-Dateien in einem neuen Ordner namens `doc` gespeichert werden. Dort öffnest du dann die `index.html`.

Welche Fehler beim Kommentieren gibt es?

Selbst erfahrene Entwickler machen Fehler bei der Dokumentation. Hier sind die klassischen Fallstricke, die du vermeiden musst.

Fehler 1: Das Offensichtliche erklären

Der schlimmste Kommentar ist der, der nur das wiederholt, was der Code eh schon sagt.

// FALSCH: Codierung
int i = 0; // weist i den Wert 0 zu

// RICHTIG: Kontext
int i = 0; // Startindex fuer die Schleife, um das erste Element zu ueberspringen

Erkläre immer den Warum-Hintergrund (Geschäftslogik), nicht das Wie (Syntax).

Fehler 2: Kommentare nicht aktualisieren

Wenn du Code änderst, änderst du oft die Logik, aber vergisst den alten Kommentar. Das führt zu Widersprüchen. Ein falscher Kommentar ist gefährlicher als gar keiner, weil er dich in die Irre führt. Regel: Code und Kommentar gehören immer zusammen.

Fehler 3: Javadoc-Tags vergessen oder falsch nutzen

Eine fehlende Dokumentation von Parametern führt zu Warnungen bei der Dokumentationserstellung.

// FALSCH: Parameter fehlen
/**
 * Berechnet den Preis.
 * @return Der Preis
 */
public double berechnePreis(double grundpreis, int rabatt) {
  return (grundpreis * (100 - rabatt)) / 100.0;
}

// RICHTIG: Vollstaendig
/**
 * Berechnet den reduzierten Preis nach Abzug des Rabatts.
 *
 * @param grundpreis Der Ausgangspreis in Euro
 * @param rabatt     Der Rabatt in Prozent (0-100)
 * @return Der berechnete Endpreis in Euro
 */
public double berechnePreis(double grundpreis, int rabatt) {
  return (grundpreis * (100 - rabatt)) / 100.0;
}

Wie übst du am besten?

Nimm ein kleines Projekt, das du vor einiger Zeit geschrieben hast - vielleicht aus deinem Java-Arrays-Guide oder den Java-Schleifen. Gehe jede öffentliche Methode durch und füge Javadoc-Kommentare hinzu.

Versuche danach, mit `javadoc -d doc *.java` die Dokumentation zu erzeugen. Wenn du Warnungen siehst, fehlen vermutlich `@param`- oder `@return`-Tags. Das ist der beste Weg, um ein Gefühl für die Syntax zu bekommen.

FAQ

Werden Kommentare beim Kompilieren ignoriert?

Ja, komplett. Der Java-Compiler (javac) entfernt alle Kommentare und wandelt sie nicht in Bytecode um. Das bedeutet: Kommentare machen dein Programm langsamer? Nein. Sie haben null Einfluss auf die Performance zur Laufzeit.

Wann sollte ich Javadoc nutzen und wann normale Kommentare?

Nutze Javadoc (`/** */`) für alles, was nach außen sichtbar ist: öffentliche Klassen, Methoden und Attribute. Das ist deine "Schnittstelle" für andere Programmierer. Normale Kommentare (`//` oder `/* */`) nutzt du für interne Erklärungen innerhalb einer Methode, um komplexe Algorithmen zu erklären.

Kann ich HTML in Javadoc-Kommentaren nutzen?

Ja, das ist sogar sehr nützlich. Du kannst HTML-Tags wie `<code>`, `<b>` (fett), `<i>` (kursiv) oder `<p>` (Absatz) nutzen, um die generierte HTML-Seite zu formatieren. Achte dabei nur auf sauberen Code.

Was bedeutet @deprecated genau?

`@deprecated` markiert eine Methode oder Klasse als "veraltet". Sie funktioniert noch technisch, sollte aber nicht mehr für neue Entwicklungen verwendet werden, da es eine bessere Alternative gibt. Gute Entwickler ergänzen `@deprecated` immer mit einem `@see`-Link zur neuen Lösung.

Muss ich jede Zeile Code kommentieren?

Auf keinen Fall. Zu viel "Lärm" im Code stört mehr als es hilft. Kommentiere nur das, was nicht offensichtlich ist: komplexe Berechnungen, Workarounds für Bugs oder wichtige Geschäftsregeln. Wenn du Variablen wie `maximaleVersuche` benennst, brauchst du keinen Kommentar, der erklärt, dass es die maximalen Versuche sind.

Fazit

Gute Java Kommentare und Javadoc machen den Unterschied zwischen einem "Wirrwarr" und einem professionellen Software-Projekt. Als Faustregel solltest du dir merken: Kommentiere, warum etwas gemacht wird, nicht was passiert. Der Code zeigt das Was, der Kommentar das Warum.

Nutze Javadoc konsequent für alle öffentlichen Teile deiner Klassen. Es mag am Anfang wie Schreibarbeit wirken, aber es spart dir und deinem Team Stunden der Fehlersuche später.

Willst du noch tiefer in Java einsteigen? Dann lies unseren Guide zu Java-Operatoren oder erfahre, wie man Java-Methoden richtig aufbaut.

Du brauchst Unterstützung bei IT-Themen oder bereitest dich auf eine Prüfung vor? Auf study-it.education findest du kompetente Hilfe und Nachhilfe - individuell auf deinen Bedarf zugeschnitten.