Java Docs

[Ostkreuz]

Hallo ist zwar eigentlich leicht, aber was genau soll ich für die Setter und Getter in die Java Docs schreiben?

 

[mihe7]

Für so etwas schreibe ich gar keine JavaDocs aber wenn man will:

/**
 * Sets the first name of ... (z. B. this Person)
 *
 * @param firstName  first name (of this Person), may be {@code null}.
 */
public void setFirstName(String firstName) { ... }

/** 
 * Returns the first name (of this Person)
 *
 * @return String containing the first name (of this Person), might be {@code null}.
 */
public String getFirstName() { ... }

 

[yfons123]

die setter und getter javadocs kannst du dir automatisch generieren lassen durch tools

für public methoden die keine getter setter sind macht es sinn sich javadocs anzulegen

 

[LimDul]

Zu Javadoc noch eine Anmerkung.

Im reinsten Sinne von Clean Code ist jeder Kommentar den man schreibt ein Eingeständnis, dass man es nicht geschafft hat verständlichen Code zu schreiben. Grundsätzlich mal zu lernen, wie man Javadoc schreibt ist nicht schlecht. Aber wenn man das Gefühl hat, dass Javadoc was man schreibt ist im Prinzip nur ein Satz rund um Methodennamen / Parameter / Rückgabewert und bringt eigentlich keinen Mehrwert, dann ist das kein Fehler. Im Gegenteil, dann hat man alles richtig gemacht hat.

Das heißt nicht das Javadoc überflüssig ist - insbesondere wenn man Schnittstellen für andere bereitstellt sollte man sowas immer schreiben. Und oft gibt es auch Infos, die nicht aus der Methodensignatur hervorgehen, dann ist es auch gut die zu erwähnen. Aber das Ziel sollte sein, Kommentare möglichst überflüssig zu machen und sich im Code auszudrücken.

 

[Neumi5694]

Was rein sollte: Das Verhalten. Wenn ein Wert irgendwelchen Beschränkungen unterliegt, dann sollte dokumentiert werden, was die Methode damit macht.
Wenn z.B. ein Wert auf min und max korrigiert wird, dann sollte das im Setter stehen. Im Getter sollte entsprechend im Return-Bereich Zahlenbereich des Wertes angegeben werden.
Kurz: Der Benutzer dieser Methoden sollte sie nicht erst ausprobieren müssen, um zu sehen, was passiert.

Persönliche Vorgehensweise (und wirklich, es ist genau das): Was ich mir angewöhnt habe, ist, bei Get/Set Paaren für Attribute den Header der Methoden beider Methoden gleich zu lassen. Also kein "Sets the ..." und "Returns the ..." sondern einfach nur die Beschreibung des Attributs. Das irgendwas gesetzt oder returned wird, schreib ich dann in die entsprechenden @param oder @Return

Dokumentation im Code finde ich grundsätzlich nicht schlecht, vor allem bei komplexen längeren Algorithmen mit vielen Abhängigkeiten. Es ist eine Sache zu erkennen, WAS da gemacht wird, das WARUM ist zwei Jahre später aber oft viel wichtiger. Man kann natürlich auch den gesamten Algorithmus im Javadoc dokumentieren.
Wenn ich so was habe, mach ich meistens beides. Bevor ich eine Methode schreibe, wird zuerst mal im JAvadoc die Doku geschrieben, was sie machen soll. Das "wie" wird zumindest teilweise hinzugefügt, Referenzen (@see) auf andere bereits existierende public Methoden. Diese Doku wird dann in die einzelnen Punkte zerlegt, in die Methode geschrieben. Dann wird entschieden, was davon in Methoden auszulagern wäre und was nicht. Dann wird jeder einzelne Punkt umgesetzt. Die Beschreibung bleibt im oft im Code stehen, auch wenn eine Methode mit lesbarem Namen aufgerufen wird, damit man beim Lesen des Codes der Beschreibung im Header folgen kann.
Da ich oft mehrere Jahre nach Implementierung nochmal ran muss und für bestimmte Kunden Änderungen vornehmen soll, steht auch dabei, warum ich bestimmte Umsetzungsentscheidungen getroffen habe, manchmal auch, welches Ticket für den entsprechenden Block verantwortlich ist, worauf achtzugeben ist (denn sonst gibt's in Folge ein Bugticket eines anderen Kunden, der das genau so haben wollte, was ich grad geändert hab).
Doku und Entwicklung gehen Hand in Hand. In früheren Zeiten (assembler) war es nicht unüblich, jede einzelne Zeile zu dokumentieren und sei sie noch so eindeutig.

 

[KonradN]

die setter und getter javadocs kannst du dir automatisch generieren lassen durch tools

schreikrampf

Ja, das kann man machen. Es gibt da tolle AddOns. Auch für Visual Studio. Microsoft hat da mal die Neuentwicklung der Windows Workflow Foundation (WWF) an Entwickler in Indien gegeben. Der Code wurde wohl auf die Kommentare geprüft, also hat man ein solches AddOn verwendet.

Die ganze Dokumentation der WWF 4.0 auf MSDN war dann zu 100% autogeneriert.

Die Freude bei Entwicklern kann man gar nicht gut genug beschreiben!

Einfach mal vergleichen, was denn so in den JavaDoc einer Klasse so alles steht. Und dann vorstellen, das wäre alles weg.

Also da dann ggf. überlegen, ob man nicht mit dem Team diskutiert, dass man ganz auf JavaDoc verzichtet. Denn das führt JavaDoc schlicht ins Absurde. Code, der einfach nur generiert wird ist Platzverschwendung. Und das gleiche gilt für Kommentare.

 

[Neumi5694]

Code, der einfach nur generiert wird ist Platzverschwendung. Und das gleiche gilt für Kommentare.

/**
 * This sets the name
 * @param name the name
 */
public setName(String name){}

/**
 * This returns the name
 * @return the name
 */
public String getName(){}

Auto-Generierung ist doch Spitze!

 

[LimDul]

/**
 * This sets the name
 * @param name the name
 */
public setName(String name){}

/**
 * This returns the name
 * @return the name
 */
public String getName(){}

Die Kommentare sind unsinnig. Was ist der Mehrwert dieses Kommentars?

Solche Kommentare kann und sollte man weglassen.

 

[Neumi5694]

Die Kommentare sind unsinnig. Was ist der Mehrwert dieses Kommentars?

Solche Kommentare kann und sollte man weglassen.

Du hast das Anschauungsbeispiel also verstanden.

 

[KonradN]

Also ich bereite gerade eine kleine Video Serie zu Clean Code vor, wo ich eine EInführung in TDD und auch statische Codeanalyse und so mache ...

Da ich in dem Video natürlich nicht 2 Stunden zeigen will, wie ich Kommentare schreibe, nutze ich da ein JavaDoc Plugin, das mir Kommentare gerzeugt. So Kommentare sind hilfreich, da ja die Entwicklungsumgebung diese einblendet. Beispiel:

Der Kommentar "The constant MIN_VALUE." bringt wirklich viel Mehrwert.
a) MIN_VALUE ist natürlich eine Konstante - sonst wäre es ja minValue ...
b) Die Deklaration hat IntelliJ auch eingeblendet.

Und da macht natürlich ein anderer Kommentar Sinn. Halt etwas wie: "FizzBuzz Werte sind nur für ganze Zahlen größer 1 definiert." Es ist etwas einfaches, da etwas sinnvolles zu sagen.

Bei Getter / Setter wird es etwas schwieriger. Da läuft es teilweise wirklich auf etwas hinaus, das auch automatisch generiert werden kann. Aber das sind Ausnahmen.

Das Problem, wenn sowas generiert wird: Man packt es nicht an und macht daher nichts. Damit fehlt dann auch eine Information a.la. "Der Name darf nicht leer oder null sein" (So es ein Pflichtwert ist). Das wird im Code sichtbar sein, da eine @NonNull oder @NotNull Annotation vorhanden ist (hoffentlich! Aber wen interessiert statische Codeanalyse schon. Erst wenn man zu Kotlin gewechselt ist, dann ist Java scheiße, weil es da mit null ja so große Probleme hat ... Aber bei Kotlin hat man natürlich auch keine statische Codeanalyse ... wenn also eine neue Sprache Kotlin ablöst, dann ist Kotlin scheiße, weil es irgend etwas nicht prüft, das ja die neue Sprache als festen Bestandteil hat!).

Getter / Setter kann man auch einfach gar nicht schreiben. Dann nutzt man Lombok und hat dieses Problem erst gar nicht. Das würde ich bevorzugen gegenüber der Ich generiere einfach alles ... Code und Kommentare kann ja alles die IDE generieren.

Ja, ich nutze es auch, aber ich überarbeite das dann. So wie die IDE mir auch einen Rahmen erzeugt, wenn ich /** eintippe. Das ist nur ein erweiterter Rahmen, was da generiert wird.