JavaDoc

🚧

Diese Seite befindet sich in Bearbeitung

🚧

🤓

Diese Seite ist eine Bewertungsrichtlinie, die ab Blatt 2 annotiert und ab Blatt 3 abgezogen wird.

🤓

Beschreibung

Neben regulären Kommentaren bietet Java zusätzlich noch JavaDoc Kommentare, die sich als Industriestandard herauskristalisiert haben. Oracle beschreibt JavaDoc's wiefolgt:

"You can include documentation comments ("doc comments") in the source code, ahead of declarations of any class, interface, method constructor or field. You can also create doc comments for each package and another one for the overview, though their syntax is slightly different. Doc comments are also known informally as "Javadoc comments" (but this term violates its trademark usage). A doc comment consists of the characters between the characters /** that begin the comment and the characters */ that end it. Leading asteriks are allowed on each line and are described further below. The text in a comment can continue onto multiple lines."

Es handelt sich also um eine Art der Dokumentation, die dafür gedacht ist, die Verwendungsweise des Codes zu Dokumentieren. Das kann Beschreibungen, Beispiele, Ein- und Ausgabefelder beinhalten, sowie andere Informationen und Verweise die zum Verstehen der Verwendung notwendig sind.

(Fun Fact: Die Doc Kommentare wurde nicht von Oracle entwickelt, sondern von Sun Microsystems. Ab Version 2 ist es aber ein Bestandteil des Java Development Kits JDK)

Das ist jetzt viel Text, der zu verstehen und vertiefen ist. Fangen wir mit der Syntax an:

Format/Syntax

Ein Auszug aus der Dokumentation zu den Doc Kommentaren:

/**
* Returns an Image object that can then be painted on the screen. 
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument. 
* <p>
* This method always returns immediately, whether or not the 
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives 
* that draw the image will incrementally paint on the screen. 
*
* @param  url  an absolute URL giving the base location of the image
* @param  name the location of the image, relative to the url argument
* @return      the image at the specified URL
* @see         Image
*/
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}

Was ist hier zu sehen?

Kommentare starten mit /** und enden mit */, jede Zeile beginnt mit einem * (das ist ab JavaDoc 1.4 optional, ist aber besserer Stil)
Der obere Teil stellt eine Beschreibung der Methode, einmal eine kurze Zusammenfassung und darunter eine detailreichere Beschreibung.
Das Doc Kommentar ist mit HTML formatiert, d.h. es können Tag wie <p> verwendet werden um die Doc Kommentare zu stilisieren
Zwischen der Beschreibung und den "Block Tags" ist eine Leerzeile einzufügen.
Es gibt genau einen Abschnitt für die Beschreibung und einen für die Block Tags. Das heißt, dass nach den Block Tags keine Beschreibung mehr folgen kann und darf.
Es wird empfohlen, Zeilen nicht länger als 80 Zeichen zu schreiben, damit die Zeilen nicht wrappen.

Was sind diese "Block Tags"?

Block Tags beschreiben einzelne Parameter, Ausgabewerte, Fehlertypen, etc genauer und es ist direkt ersichtlich, was die Ein- und Ausgabeformate sind ohne die Beschreibung oder Beispiele zu durchforsten. Dafür gibt es einige Tags, die wir etwas genauer betrachten:

@author name-text: Ergänzt einen oder mehrere Autoren für dieses Doc. Für mehrere Autoren können mehrere Tags benutzt werden, müssen aber nicht.
@exception class-name description: Eine veraltete Version des @throws-Tag, welcher bevorzugt benutzt werden sollte.
@param parameter-name description: Ergänzt einen Parameter und eine passende Beschreibung.
@return description: Ergänzt eine Beschreibung, die den Typ und die Werte die er haben kann dokumentiert (Kann nur bei Methoden verwendet werden).
@see "string" oder <a href="url">label</a> oder package.class#member label: Verweist auf weitere Referenzen zu diesem Doc.
@throws class-name description: Die neue Version des @exception-Tags. Es soll hier beschrieben werden, welche Exception geworfen wird und in welchen Fällen sie auftritt.

Achtung:

Wir bemerken, dass die Block Tags alle mit einem @ Symbol starten und erinnern uns, dass nach einem Block Tag keine Beschreibung mehr folgen darf. In dem obigen Auszug ist allerdings innerhalb der Beschreibung ein Tag vorhanden (@link URL). Das ist kein Block Tag, sondern ein "Inline Tag". Die genaue Auflistung der Block- und Inline Tags ist hier zu finden und nachzulesen.

Beschreibung/Semantik

Das Doc Comment soll mit einem Satz beginnen, der kurz aber vollständig zusammenfasst, was passiert. Das ist wichtig, weil genau dieser Satz in der Paket-Zusammenfassung vorkommt.

Für die folgende Beschreibung ist unter anderem folgendes wichtig:

Implementation independent: Die Beschreibung sollte keine Implementierungsdetails preisgeben, von denen es nicht zwingend notwendig ist, diese zu kennen. In der Regel gilt: "write once, run anywhere".
Automatic reuse of method comments: In folgenden Szenarien, wird das Doc Comment "mitvererbt": Klasse überschreibt eine Methode in der Superklasse, Interface überschreibt Methode im Superinterface, Eine Klassenmethode implementiert eine Methode eines Interfaces.

Stil

in-line Links: in-line Links dürfen verwendet werden und sind gerne gesehen, sollten aber keine Überhand nehmen. Insbesondere sollte jeweils nur das erste Vorkommen eines zu verlinkenden Artikels auch wirklich verlinkt werden. Redundanz sollte dringend vermieden werden, da sonst die Aufmerksamkeit von der Dokumentation weggeführt wird. Auch ist es wichtig, nicht immer alles zu verlinken, sondern nur das relevanteste.
In 3. Person verfassen: Dokumentation sollte nicht in der 2. Person, sondern der 3. Person verfasst werden (siehe Beispiel unten).
Methodenbeschreibungen starten mit einem Verb: siehe Beispiel unten
Reihenfolge der Block-Tags: Als Reihenfolge für die Block-Tags gibt Oracle folgende Konvention:

@author
@version
@param
@return
@throws
@see
@since
@serial
@depricated

Ort

Doc Comments sind an allen Stellen zu verfassen, die eine andere Sichtbarkeit als private haben.

Weiteres zu Konventionen zu Doc Comments kann hier nachgelesen werden.

Negativbeispiel

/**
 * This is a game.
 * @see otherGame
 * @author someone
 */
public class Game {

    /**
     * Do a turn and see what happens.
     * @throws IllegalArgumentException because why not
     */
    public boolean doTurn() throws IllegalArgumentException {

    }
}

Positivbeispiel

/**
 * Implements a generic game.
 * @author AwesomeDeveloper
 */
public class Game {

    /**
     * Simulates a turn on the board.
     * A turn can only be simulated if the player does not exit the board. In that case an error should occurr.
     *
     * @return a boolean signalling a (un)successful turn
     * @throws IllegalArgumentException if the turn could not be simulated because of a wrong input.
     */
    public boolean doTurn() throws IllegalArgumentException {

    }
}

🚧

Diese Seite befindet sich in Bearbeitung

🚧