Java - Javadoc Kommentare: Ein Anfängerguide

Hallo da draußen, angehender Java-Programmierer! Heute machen wir uns auf eine aufregende Reise in die Welt der Javadoc Kommentare. Keine Sorge, wenn du noch nie eine Zeile Code geschrieben hast – ich werde dein freundlicher Guide sein, und wir gehen das Schritt für Schritt durch. Am Ende dieses Tutorials wirst du professionell aussehende Dokumentation wie ein Profi schreiben können!

Was ist Javadoc?

Stell dir vor, du schreibst ein Kochbuch. Du würdest nicht einfach Zutaten und Schritte ohne Erklärung auflisten, oder? Genau hier kommt Javadoc ins Spiel für die Java-Programmierung. Es ist ein Werkzeug, das uns hilft, saubere, organisierte Dokumentation für unseren Code zu erstellen.

Javadoc Kommentare sind besondere Kommentare in deinem Java-Code, die in hübsche HTML-Dokumentation umgewandelt werden. Sie sind wie die zusätzlichen Notizen und Tipps, die du zu deinem Rezept hinzufügen würdest, um anderen zu helfen, es besser zu verstehen.

Warum Javadoc verwenden?

1. Es macht deinen Code für andere (und deinen zukünftigen Ich!) leichter verständlich.
2. Es ist die standardmäßige Methode zur Dokumentation von Java-Code, sodass andere Java-Entwickler sich damit vertraut machen.
3. Es kann automatisch professionell aussehende Dokumentation generieren.

Die Javadoc Tags

Javadoc verwendet spezielle Tags, um Informationen zu organisieren. Denke daran, dass diese Tags wie Rubriküberschriften in deinem Kochbuch sind. Hier sind einige der häufigsten:

Tag	Beschreibung	Beispiel
@author	Gibt den Autor des Codes an	@author Max Mustermann
@version	Gibt die Version der Klasse an	@version 1.0
@param	Beschreibt einen Methodenparameter	@param name Der Name der Person
@return	Beschreibt, was eine Methode zurückgibt	@return Der berechnete Flächeninhalt
@throws	Listet Ausnahmen auf, die die Methode auswerfen könnte	@throws IOException Wenn die Datei nicht gelesen werden kann
@see	Fügt eine "Siehe auch" Überschrift mit Links zu anderen Elementen hinzu	@see String#toLowerCase()
@since	Gibt an, wann diese Funktion hinzugefügt wurde	@since 1.5
@deprecated	Gibt an, dass diese API nicht mehr verwendet werden sollte	@deprecated Verwende newMethod() stattdessen

Nun sehen wir, wie wir diese in echter Java-Sprache verwenden!

Beispiel - Verwendung von Javadoc Kommentaren

Lass uns eine einfache Rectangle-Klasse erstellen, um Javadoc Kommentare zu demonstrieren:

/**
* Diese Klasse repräsentiert eine Rechteckform.
* Sie kann die Fläche und den Umfang des Rechtecks berechnen.
*
* @author Jane Smith
* @version 1.0
* @since 2023-06-01
*/
public class Rectangle {
private double length;
private double width;

/**
* Konstruiert ein neues Rechteck mit den angegebenen Abmessungen.
*
* @param length Die Länge des Rechtecks
* @param width Die Breite des Rechtecks
*/
public Rectangle(double length, double width) {
this.length = length;
this.width = width;
}

/**
* Berechnet und gibt die Fläche des Rechtecks zurück.
*
* @return Die Fläche des Rechtecks
*/
public double calculateArea() {
return length * width;
}

/**
* Berechnet und gibt den Umfang des Rechtecks zurück.
*
* @return Der Umfang des Rechtecks
*/
public double calculatePerimeter() {
return 2 * (length + width);
}

/**
* Vergrößert das Rechteck um einen gegebenen Faktor.
*
* @param factor Der Faktor zur Größenänderung (z.B. 2.0 verdoppelt die Größe)
* @throws IllegalArgumentException Wenn der Faktor negativ ist
*/
public void resize(double factor) throws IllegalArgumentException {
if (factor < 0) {
throw new IllegalArgumentException("Größenänderungsfaktor muss positiv sein");
}
length *= factor;
width *= factor;
}
}

Lassen wir das auseinanderbrechen:

1. Der Klassenkommentar beschreibt, was die Rectangle-Klasse macht und enthält @author, @version und @since Tags.

2. Der Konstruktor hat einen Kommentar, der erklärt, was er macht, und @param Tags für jeden Parameter.

3. Die calculateArea() und calculatePerimeter() Methoden haben Kommentare, die erklären, was sie machen, und @return Tags, die beschreiben, was sie zurückgeben.

4. Die resize() Methode zeigt, wie man eine Methode dokumentiert, die eine Ausnahme auswerfen könnte, indem der @throws Tag verwendet wird.

Generierung von Javadoc HTML

Nun zur magischen Phase! Sobald du deine Javadoc Kommentare geschrieben hast, kannst du das Javadoc-Werkzeug verwenden, um wunderschöne HTML-Dokumentation zu generieren. Wenn du eine integrierte Entwicklungsumgebung (IDE) wie Eclipse oder IntelliJ IDEA verwendest, ist es normalerweise so einfach wie das Klicken auf einen Button.

Zum Beispiel in Eclipse:

1. Rechtsklicke auf dein Projekt
2. Wähle "Javadoc generieren"
3. Folge dem Assistenten, um Optionen festzulegen
4. Klicke auf "Fertig"

Und voilà! Du hast eine Reihe von HTML-Dateien, die deine Dokumentation in einem professionellen, leicht zu navigierenden Format anzeigen.

Best Practices für das Schreiben von Javadoc

1. Sei klar und prägnant: Schreibe deine Kommentare, als würdest du jemandem erklären, der deinen Code noch nie gesehen hat.

2. Dokumentiere öffentliche APIs: Konzentriere dich auf die Dokumentation öffentlicher Klassen, Methoden und Felder. Diese sind das, was andere Entwickler verwenden werden.

3. Verwende vollständige Sätze: Beginne mit einem Großbuchstaben und beende mit einem Punkt. Es macht die Dokumentation lesbarer.

4. Vermeide Redundanz: wiederhole nicht nur den Methodennamen. Füge Wert mit deinen Kommentaren hinzu.

5. Aktualisiere Kommentare: Wenn du deinen Code änderst, vergiss nicht, die entsprechenden Javadoc Kommentare zu aktualisieren.

Schlussfolgerung

Glückwunsch! Du hast die ersten Schritte in die Welt der Javadoc Kommentare unternommen. Erinnere dich daran, dass gute Dokumentation wie das Hinterlassen eines Brotkrumenpfades für andere (oder dein zukünftiges Ich) ist. Es mag jetzt wie zusätzlicher Aufwand erscheinen, aber glaub mir, du wirst dich später bedanken, wenn du nach sechs Monaten zu deinem Code zurückkehrst und genau verstehen kannst, was los ist.

Übe weiter, und bald wird das Schreiben von Javadoc Kommentaren zur zweiten Natur. Viel Spaß beim Programmieren und möge dein Code stets gut dokumentiert sein!

Credits: Image by storyset