-
Notifications
You must be signed in to change notification settings - Fork 0
code doc
Eine korrekte Dokumentation ist genau so Teil eines abgeschlossenen Meilensteins wie ein funktionierender Build. Bevor auf dev gepusht wird ist also nicht nur darauf zu achten, dass sich der Code compilieren und ausführen lassen soll, sondern auch, dass die Dokumentation vollständig ist und fehlerlos zu generieren ist. Generell wird alles in Englisch kommentiert, genau wie die Benennungen von Klassen, Methoden und Variablen sich am Englischen orientieren.
Jede Klasse und jedes Interface müssen am Beginn des Files eine Erklärung des Zwecks dieser Klasse haben.
Methoden die nicht von Interfaces oder Super-Klassen geerbt sind müssen vollständig kommentiert werden. Sind sie vererbt kann die JavaDoc für diese Methode weggelassen werden. Beim generieren der JavaDoc wird dadurch automatisch die Dokumentation der Super-Klasse für diese Mehode übernommen. Wenn es aber wirklich besondere Unterschiede zur Definition in der Super-Klasse gibt, kann durchaus eine angepasste Version der JavaDoc direkt in die Klasse geschrieben werden, die dann die Dokumentation der Superklasse für diese Methode überschreibt. Auch private- und protected-Methoden müssen kommentiert werden. Sie tauchen zwar je nach Einstellung nicht in der generierten JavaDoc auf, sind sie kommentiert wird das Verständnis für die Klasse aber für uns sehr viel leichter.
Vor- und Nachbedingungen werden nicht in JavaDoc sondern in normalen Kommentaren (Einzeilige bzw. mehrzeilige Kommentare mit nur einem Stern) vor der entsprechenden Methode geschrieben.
Wenn in Methoden besonders ausgefeilte Algorithmen oder Konstrukte verwendet werden die eher nur schwer verständlich sind, kann und soll auch direkt im Code an den betreffenden Stellen kommentiert werden um es anderen zu erleichtern den Code zu verstehen. Entweder mit einzeilgen ("//...") oder mehrzeiligen Kommentaren aber logischerweise keine JavaDoc-Kommentare.
Verwendet den "//TODO: ... " Kommentar großzügig! Wenn ihr Methoden nicht auf eine Sitzung fertig schreibt dann verseht sie mit einem TODO, dasselbe gilt für automatisch generierte, geerbte Methoden. So läuft man nicht Gefahr leere oder unfertige Methoden erst beim Testen zu finden. Das TODO-Tag soll immer in einem eigenen, non-JavaDoc Kommentar stehen, also nicht in die Documentation-Kommentare geschrieben werden und auch nicht in denselben Kommentar mit den Pre- und Postconditions.
Die Erklärung der Klasse/des Interfaces steht am Anfang des Files. Das Tag @author werden wir nicht verwenden, die Verfolgung der Autoren über Git ist präziser und verlässlicher.
/**
This class represents a foo.
*/
public class foo{
...
}In IntelliJ Idea wird beim Öffnen eines Kommentars mit zwei Sternen direkt vor einer Funktion automatisch eine Java-Doc-Vorlage erstellt. @param, @returns und @throws sind darin enthalten soweit sie für diese Methode nötig sind und müssen auch verwendet und ausgeschrieben werden.
Ein Spezialfall sind bei uns die Entity-Klassen, dort kann die Methodenbeschreibung sowohl für getter und setter als auch Konstruktor vollständig weggelassen werden, es soll nur im Kopf der Klasse beschrieben sein was repräsentiert wird.
Eventuelle Preconditions und Postconditions für Tests, aber auch für die normale Nutzung im Fotostudio-Programm werden vor der Klasse in Non-JavaDoc-Kommentaren definiert.
/*
Precondition: the database must be up and running
Postcondition: none
*/
/**
* This method takes a String, does something and returns the string unaltered.
* @param bar A string of any form or length.
* @return the same string that was given as input-parameter.
*/
public String foo(String bar){
...
return bar;
}In JavaDoc kann man HTML-Tags zur Formatierung verwenden. Alle Ausdrücke die in Winkel-Klammern stehen (zum Beispiel <div>) werden also als HTML-Tags interpretiert, das führt aber auch zu Problemen mit generischen Datentypen. So wird bei List<String> versucht "String" als HTML anzuzeigen. Um dieses Problem zu umgehen gibt es das Tag @literal.
Wieder am Beispiel von List<String> sieht die Syntax des @literal-Tags folgendermaßen aus:
List{@literal <String>}
Auchtung: JavaDoc nicht in Git synchronisieren!
Um die JavaDoc des Projekts zu erstellen kann das in IntelliJ integrierte Tool verwendet werden. Es ist zu finden unter "Tools->Generate JavaDoc". Wird versucht über dieses Tool die JavaDoc zu generieren gibt es, genau wie der Compiler, Warnungen aus wenn etwas nicht den Vorgaben entspricht und entdeckt so zum Beispiel fehlende Beschreibungen bei Tags und Tags die nicht zur Methode passen oder fehlen.
Das Tool kann verwendet werden um die Documentation des ganzen Projekts zu generieren, man kann aber auch Scopes einstellen, sodass die Doc nur für Teile des Programms generiert wird. Dazu stehen folgende Einstellungen zur Verfügung:
- Whole Project
- Uncommited Files
- Custom Scope
Whole Project ist wohl selbsterklärend. Mit Uncommited Files - All generiert man für alle Files die noch nicht Committed sind. Unter Custom Scope lässt sich ein eigener Scope einstellen, für den dann generiert werden kann. Dabei gibt es einige Vorgefertigte Scopes, zum Beispiel "Current File", "Production Files" (->src-Ordner) oder "Test Files" (->test-Ordner) das wirklich interessante hier sind aber Custom Scopes. Neben der Scope-Auswahl ist ein Button der zum Definitionsfenster für Custom Scopes führt. Dort kann man eigene Scopes hinzufügen und definieren welche Packages oder Files in diesen Scope eingefügt werden sollen. So kann man Scopes definieren die Beispielsweise nur die DAO und Service-Packages generiert, oder zum Beispiel die Klassen die zur Profile-Komponente gehören. Neue Scopes sollten generell als Lokale Scopes definiert werden, anderenfalls werden sie in Git synchronisiert, was ich nicht für sinnvoll halte.
Eine weitere wichtige Einstellung ist der Slider mit den Visibility-Levels, von public bis private. Zum Testen ob die Dokumentation generiert werden kann muss natürlich immer private ausgewählt werden, so wird für alle Member generiert, ganz egal welches Visibility-Level vorliegt.
Von den sonstigen Einstellungen kann alles so gelassen werden wie es ist, abgesehen vom Output Directory das definiert werden muss.