Was sollte man ins JavaDoc implementieren??

Diskutiere Was sollte man ins JavaDoc implementieren?? im Allgemeine Java-Themen Bereich.
M

MiMa

Ich habe mir schon früh angewöhnt JavaDoc Kommentare einheitlich zu implementieren damit auch später noch den Überblick habe.
Allerdings habe ich mich gefragt, ob private Variablen überhaupt deklariert werden sollten.
Es nimmt schon ganz schön Zeit in Anspruch aber ich habe mich immer gefragt ob es nachher nicht viel mehr Zeit vertan wird wenn man keine vernünftige Dokumentation hat. Zum einen sollen sie Privat sein und auf der anderen Seite soll das JavaDoc doch den Entwickler unterstützen.
Ich habe die privaten Variablen in ein paar Klassen Dokumentiert, aber im JavaDoc konnte ich die nicht finden.
Wird nicht alles im JavaDoc angezeigt wars entsprechend Kommentiert wird?

Jetzt frage ich einfach mal was überhaupt Dokumentiert werden sollte.
Danke
Mi
 
J

JustNobody

Also was man in die Doku setzt oder nicht hängt in erster Line davon ab, für wen die Dokumentation ist. In der Regel würde ich da Moxxi zustimmen: die Zielgruppe interessiert das nicht. Aber ich möchte nicht ausschließen, dass es diese Anforderung auch geben kann, daher schauen wir einfach die technische Seite:

JavaDoc unterstützt das natürlich. Wenn man sich die Doku ansieht, dann sieht man die Option -private die dafür sorgt, dass auch private Elemente mit ausgegeben werden.
Sieht z.B. https://docs.oracle.com/javase/9/tools/javadoc.htm#JSWOR-GUID-9D532574-1CDB-4D30-99F3-A308DCAEE55F
 
mihe7

mihe7

Jetzt frage ich einfach mal was überhaupt Dokumentiert werden sollte.
Alles. Die Frage ist nur, in welcher Weise :)

Der überwiegende Teil sollte in Form von Code dokumentiert sein. Es macht überhaupt keinen Sinn, zu beschreiben, was Dein Code macht - das steht im Code. Das ist z. B. ein Grund, warum man aussagefähige Bezeichner wählen sollte.

Mist:
Java:
/** Berechnet den Sinus.
 * @param v  Winkel im Bogenmaß.
 * @return Sinus von v
 */
double f(double v) {
...
}
Hat nicht mehr Informationsgehalt als:
Java:
double sinus(double bogenmass) {
...
}
Noch "besser":
Java:
/** Der Name. */
private String name;
WTF?!?

Der Umfang der JavaDocs hängt natürlich auch von der Zielgruppe ab, wie @JustNobody bereits geschrieben hat.
 
M

MiMa

JavaDoc Einträge bei den Variablen zu deklarieren, da kam mir irgendwann auch der Gedanke, ob das wirklich sinn macht, da ich sowieso selbstsprechende Variablen verwende. Ich wollte wohl einen besseren Überblick über die Variablen haben, was so aber nicht funktionierte.
Auch gerade als Anfänger nimmt man gerne die Hilfe der IDE an und lässt dann bei "missing javadoc" die Einträge erstellen.
Selbst bei den get und set Methoden wird es angezeigft und daher hatte ich am Anfang selbst dort die Einträge.
Mittlerweile bin ich dazu übergegangen public Methoden in JavaDoc zu integrieren und schreibe dort eine kurze Notiz über die Methode und welche Parameter mit Dateityp erwartet werden und was mit welchem Datentyp zurück gegeben wird.
 
M

M.L.

Für Softwaretests könnte eine umfassende Dokumentation privater Variablen/Methoden auch ganz interessant sein: wenn diese nicht verwendet werden, könnte man die verantwortlichen Entwickler nach dem Sinn dieser Deklaration befragen.
 
T

thecain

Für das brauch ich doch kein Javadoc, das kann ich auch so Fragen
 
L

LimDul

Ich bin da ganz bei @mihe7
Javadoc: So wenig wie möglich, so viel wie nötig.

Grundsätzlich gilt für mich: Dokumentation privater Teile oder Inline Kommentare sind ein Code Smell. Die deuten meist drauf hin, dass irgendwas nicht gut ist. Denn wenn der Code gut und verständlich ist, wären diese Kommentare überflüssig.

Und auch public API sollte so knapp wie möglich beschrieben sein. Die Namen der Parameter und die Typen, sowie der Rückgabewert sind in jeder IDE, die den Namen verdient sichtbar. Das heißt, wenn ich im Javadoc schreibe "Die Methode ermittelt im übergebenen String die Gesamtzahl an Leerzeichen. Tabluatoren und ähnliches wird nicht gezählt" brauche ich keine weitere Dokumentation - der Rückgabewert (int) sollte klar sein und der übergebene String auch. Die noch mal extra zu beschreiben wäre Redunanz.

Je mehr man allerdings eine API schreibt, die auch fremde verwenden sollen, um so mehr Dokumentation wird sinnvoll. Hier ist wieder relevant - wer ist die Zielgruppe. Allerdings muss man auch da bedenken, dass es nicht sinnvoll ist, zu viel Redunanz zu erzeugen, sondern die Doku dann mit sinnvollen Dingen erweitert. Apache Commons hat z.B. bei vielen Methoden in StringUtils im JavaDoc Beispiele (aka Unit-Tests) stehen. Denn eigentlich sind Unit-Tests eine viel bessere Dokumentation als Javadoc. Denn Unit-Tests geben den Ist-Zustand wieder (JavaDoc einen Stand, der vielleicht aktuell war als die Doku geschrieben wurde). Gute Unit-Tests zeigen valide und nicht Valide Eingaben auf, zeigen Grenzwerte und Sonderfälle.


Für Softwaretests könnte eine umfassende Dokumentation privater Variablen/Methoden auch ganz interessant sein: wenn diese nicht verwendet werden, könnte man die verantwortlichen Entwickler nach dem Sinn dieser Deklaration befragen.
Auch hier ist Dokumentation nur das Symptom eines anderen Problems, eines nicht funktionierenden QA Prozesses. Denn private Variablen oder Funktionen, die nicht verwendet werden, dürften es normalerweise nie in echten Code schaffen. Da sollten IDE und Build-Tools schon vorher die Flagge heben und den Merge blockieren.
 
M

MiMa

Um einen besseren Überblick über Variablen, Konstruktoren und Methoden zu bekommen schreibe ich nun eine Kommentarzeile mit eigenen Schlüsselwörter im Quellcode und nutze dann in Netbeans die "Action Items" und den "Action Items Filter". Funktioniert bestens und kann dann Filtern nach Variablen, Methoden, was noch zu prüfen und zu erledigen ist. Außerdem lässt sich das noch weiter ausbauen.
JavaDoc halte ich für sehr praktisch, da ich beim schreiben der Methode immer eine Gedächtnisstütze über die Parameter und deren Datentyp bekomme. Gerade wenn das Programm wächst ist es hilfreich.

Von Unit Tests habe ich immer mal wieder etwas gehört, aber mich noch nie damit beschäftigt, wird wohl Zeit?
Auch wenn ich das Programm nur für mich zum eigenen Gebrauch programmiere, möchte ich es dennoch korrekt machen und neben den Lerneffekt auch Techniken verwenden die üblich sind.
 
Zuletzt bearbeitet:
L

LimDul

Um einen besseren Überblick über Variablen, Konstruktoren und Methoden zu bekommen schreibe ich nun eine Kommentarzeile mit eigenen Schlüsselwörter im Quellcode und nutze dann in Netbeans die "Action Items" und den "Action Items Filter". Funktioniert bestens und kann dann Filtern nach Variablen, Methoden, was noch zu prüfen und zu erledigen ist. Außerdem lässt sich das noch weiter ausbauen.
JavaDoc halte ich für sehr praktisch, da ich beim schreiben der Methode immer eine Gedächtnisstütze über die Parameter und deren Datentyp bekomme. Gerade wenn das Programm wächst ist es hilfreich.
Das sollte dir die IDE auch so anzeigen ohne Javadoc. Netbeans kenne ich jetzt nicht, aber in Eclipse sieht man das auch so:

1589955907841.png
 
M

MiMa

Ja, das macht Netbeans auch.
Das sind ja die Werte die im Methodenkopf deklariert werden.
Wenn das in der Regel ausreichen soll, wozu ist dann JavaDoc überhaupt integriert?
Nur für Bibliotheken als Wiederverwendung in andere Projekte?
Im Grunde soll man ja alles wiederverwenden um redundante Codezeilen zu vermeiden.

Aktuell nutze ich auch das Filtern um doppelte Variablendeklarationen und Methoden auf zu spüren.
Gerade beim zusammensetzen von Quellcode aus verschiedenen Projekten ist es sonst ziemlich unübersichtlich.

Also werde ich JavaDoc so wenig wie möglich und so viel wie nötig benutzen.
 
Zuletzt bearbeitet:
L

LimDul

Vielleicht noch mal einen Punkt von mir, da wir hier so sehr gegen "zu viel" Dokumentation argumentieren.

Es ist definitiv nicht falsch, Dokumentation zu schreiben. Und es ist sinnvoller - vor allem am Anfang - lieber mal etwas mehr zu schreiben. Das wichtigste beim Programmieren ist, dass man den Anspruch hat, vernünftige Software zu schreiben. Du versuchst das gerade dadurch zu erreichen, dass du relativ viel Javadoc schreibst. Das ist um Längen besser, als jemand der sagt "Man soll nur wenig Dokumentation schreiben" und schlampigen Code abliefert. Denn du wirst auch beim Dokumentation schreiben (hoffentlich) feststellen, wenn irgendwas seltsam ist. Wenn du für eine Methode auf einmal 20 Zeilen Javadoc schreiben musst, um zu erklären, was sie tut, merkst du selber, dass die Methode vielleicht etwas zu komplex ist.

Oder wenn du private Variablen dokumentierst und feststellst - du kannst gar nicht so richtig beschreiben, was sie tut - dann kommt vielleicht der Reflex noch mal drüber nachzudenken, ob da nicht was umbaut. Und im Idealfall kommt man dann am Ende zu Code, bei dem sagt "Die Dokumentation kann ich mir auch schenken, weil sie gegenüber den Code keinen Mehrwert bietet". Und es ist noch kein Meister vom Himmel gefallen und der Weg dahin besteht aus vielen Einzelschritten wo "zuviel" Javadoc schreiben durchaus ein sinnvoller Schritt sein kann.
 
mihe7

mihe7

Wenn das in der Regel ausreichen soll, wozu ist dann JavaDoc überhaupt integriert?
Es lässt sich nicht alles mit Bezeichnern und Typen auf einfache Weise ausdrücken :)

Verwendungs- bzw. Implementierungshinweise kommen durchaus ins JavaDoc. Ein Beispiel ist PrintStream#printf. Die Methode verlangt einen String als format-Parameter. Das alleine hilft wenig, man muss schon wissen, wie der Format-String aufgebaut sein muss.

Mir ging es nur darum, dass Kommentare (ganz allgemein, nicht nur JavaDoc) nichts enthalten sollten, was man bereits im Code stehen hat oder stehen haben könnte. Der Grund dafür ist ganz einfach: Kommentare sind toter Text. Dem Compiler ist es vollkommen egal, was Du kommentierst. Das hat zur Folge, dass man bei einer Änderung im Code prinzipiell auch den Kommentar überprüfen muss. Übersieht man das, beschreibt der Kommentar irgendwann ggf. etwas völlig anderes. Somit bedeutet jeder Kommentar einen gewissen Arbeitsaufwand, der nichts zum Endprodukt beiträgt, und der muss gerechtfertigt sein.

Mal ein Beispiel für schlechte Kommentare im Code:
Java:
public void machwas(List<T> liste) {
    // Wenn die Liste leer ist, ...
    if (liste.isEmpty()) {
        return; // beenden
    }

    // Erst mal Duplikate entfernen
    ...
    // Dann dieses
    ...
    // Und zum Schluss noch jenes
    ...
}
Das sind Kommentare, die beschreiben, was der Code macht. Völliger Blödsinn: ich sehe, dass auf liste.isEmpty() geprüft wird und ggf. per return zurückgesprungen wird, das braucht mir keiner dazuschreiben. Der Rest ist nicht minder unsinnig. Dabei wird der Code mittels Kommentaren strukturiert -> Tonne. Für den Zweck hat man sprachliche Mittel: Klassen und Methoden.

Kommentare im Code enthalten in erster Linie Hinweise, warum etwas wie gemacht wurde. Zum Beispiel kann es sein, dass Du eine Bibliothek verwendest, die einen Bug enthält und Du daher einen Workaround implementieren musstest. Dann schreibt man das eben dazu, damit kein anderer auf die Idee kommt, den Code durch den vermeintlich korrekten und kürzeren Code zu ersetzen.
 
M

MiMa

Hier mal ein paar Beispiel wie damals angefangen hatte JavaDoc zu schreiben, die und teilweise noch im Quellcode vorhanden sind.
Variablen
Java:
/**
* Enthält den Datei-Typ.<br>
* <b>(application/pdf,...)</b>
*/
// pVar   medienTyp : MediaType
private MediaType medienTyp;
Get-Methode
Java:
/**
* Holt den Datei-Typ.<br>
*
* @return medienTyp <b>MediaType</b> (application/pdf)
*/
// getFunk   getMedienTyp : MediaType
public MediaType getMedienTyp() {
   return this.medienTyp;
} // getMediaTyp
Set-Methode
Java:
 /**
  * Speichert den Datei-Typ.<br>
  *
  * @param medienTyp <b>MediaType</b> (application/pdf)
  */
// setFunkt   setMediaTyp(MediaType medienTyp) - Pruefen
   public void setMedienTyp(MediaType medienTyp) {
   this.medienTyp = medienTyp;
} // setMediaTyp
Methoden
Java:
/**
     * Ermittelt den Medien-Typ einer Datei.<br>
     *
     * @param datei <b>File</b> (LW:/Pfad/Name.Endung)
     * @return medienTyp : <b>MediaType</b> (application/pdf)
     * @throws IOException <b>E/A Ausnahmen</b>
     * @throws TikaException <b>Tika Ausnahmen</b>
     */
    // pFunk   sucheMedienTyp(File datei) : MediaType
    public static MediaType sucheMedienTyp(File datei) throws IOException, TikaException {
        MediaType medienTyp = null;
        if (datei.exists()) {
            // Tika-Objekt erzeugen
            Tika fileTyp = new Tika();

            // Ermittelt den Dateityp mit Hauptklasse / Unterklasse (Application/pdf)
            String typ = fileTyp.detect(datei);      // (plain/text)

            // Ermittelt den Medien-Typ  
            medienTyp = MediaType.parse(typ);  // (plain/text)
            LOG.info("Der Medien-Typ wurde ermittel      : " + medienTyp.toString());
        } else {
            LOG.error("Die Datei zum ermitteln des Datei Medien Types wurde nicht gefunden.");
        }
        return medienTyp;
    } // sucheMedienTypen
Vielleicht doch ein bisschen zu viel, aber das schreiben von JavaDoc hat sich so bei mir eingewöhnt, das es aktuell schwer ist keine zu schreiben.
 
T

thecain

// pFunk sucheMedienTyp(File datei) : MediaType
Unnötig
Java:
} // sucheMedienTypen
Unnötig
* Speichert den Datei-Typ.<br>
Falsch? Hier wird ja nichts gespeichert, sondern nur ein setter aufgerufen

So würde ich jetzt deine Kommentare sehen. Aber das ist _meine_ Meinung. Schlussendlich kann das jeder so machen wie es für ihn passt.

Ich persönlich mache Kommentare nur dann, wenn ich etwas erklären will, dass im Code nicht einfach so geht. Beispielsweise WARUM, dass etwas etwas so gemacht wurde. Oder wenn gewisse Vorbedingungen bestehen, welche im Code nicht gut abgebildet sind.
 
J

JustNobody

Also erst einmal ein paar Punkte:
a) JavaDoc: Hier geht es ja eben um die Erläuterung der Schnittstelle, damit ich mir eben nicht mehr den Code ansehen muss. Da kommt dann also später etwas raus, das man sich so ansehen kann. Und auch die Zielgruppe ist dann teilweise eine andere: Um die erstellte Dokumentation zu lesen braucht man eben keine Java Kenntnisse.
b) Da das Resultat eben etwas ist, für das man kein spezifisches Wissen mehr braucht, ist dies eine gute Ausgangsbasis um Dokumentation zu erstellen. Wenn man spezielle Kommentare verwendet, dann kann man da Dokumentation und Code zusammen halten. So muss ich nicht in andere Programme wechseln (ggf. mit anderen Ablageorten oder "binary" Dateien in der Source Verwaltung) ...

Also bei unserem Build Prozess fällt hinten auch gewisse Dokumentation raus. Welche Business Regeln an welcher Stelle wieso implementiert wurden. Das interessiert den Kunden, der aber eben kein Entwickler ist und sich C++ oder Java Code nie ansehen würde...

Generell macht diese Dokumentation aber auch nur Sinn, wenn man wirklich etwas neues hinzu fügt. Aus meiner C#/Visual Studio Zeit kenne ich noch ein AddOn, das Kommentare automatisch geschrieben hat. Da hat man eine Property name mit get/set gehabt und schon hatte man "Gets or sets the name." als Kommentar.

Ich weiß nicht ob es immer noch so ist, aber damals war die ganze Dokumentation der Workflow Foundation genau dieser Schrott. Bei sowas wird klar, dass dies nicht wirklich etwas an Mehrwert bringt. Alles, was man damit erreicht, ist das Ruhigstellen der statischen Codeanalyse so diese eben genau dies prüft und ggf. ein commit verhindern würde ...
 
mihe7

mihe7

Hier mal ein paar Beispiel wie damals angefangen hatte JavaDoc zu schreiben
Ja, so fängt wohl jeder an:

Und es ist sinnvoller - vor allem am Anfang - lieber mal etwas mehr zu schreiben.
Aber, wenn Du Deinen Code anschaust, dann erkennst Du das Prinzip, oder? :) So lange Du alleine arbeitest, kannst Du natürlich dokumentieren, was Du für richtig/wichtig hältst.

Mal aus meiner Sicht: ich wäre schon einmal verwirrt, weil da application/pdf dokumentiert wird. Noch verwirrter wäre ich, wenn dann im Code text/plain steht. Das mit dem "Speichern" hat @thecain schon angesprochen.

Jetzt schauen wir uns mal den Spaß an:
Java:
    public static MediaType sucheMedienTyp(File datei) throws IOException, TikaException {
Dein Kommentar kommentiert nun genau das, was hier schon steht. Das, was hier nicht steht, taucht hingegen im Kommentar nicht auf: datei darf nicht null sein, sonst gibt es eine NullPointerException und das Ergebnis wird null sein, wenn datei nicht existiert. Das sind die Dinge, die mich als Verwender dieser Methode interessieren würden.
 
M

MiMa

Ich denke das ich meine JavaDoc und auch Kommentare etwa in diese Richtung optimieren werde. Das ganze artet nämlich ganz schön in Arbeit aus. Es ist zwar schön im JavaDoc übersichtlich nachschlagen zu können aber steht das dann in Relation zur Arbeit die man dann da rein steckt.
Außerdem sollte das dann auch einheitlich sein und das ist auch schon so eine Sache :)

Variablen
Für mich ist wichtig was steckt drin und gebe immer ein Beispiel an. Das mache ich durch den Kommentar und benötige dafür kein JavaDoc.
Java:
/*pVar*/ private MediaType medienTyp; // application/pdf,..
Get-Methoden
Java:
/*getFunk*/ public MediaType getMedienTyp() {
   return this.medienTyp; // application/pdf,...
}
Set-Methoden
Java:
/*setFunkt - Pruefen*/ public void setMedienTyp(MediaType medienTyp) {
   this.medienTyp = medienTyp; // application/pdf,...
}
Get -und Set Methoden holen oder speichern Werte in die Instanzvariable und das Verhalten sagt im Grunde schon die Methode aus.
Daher wäre eine JavaDoc auch hier auch nicht wirklich nötig und gebe auch hier wieder ein Beispiel des inhaltes als Kommentar an.
Meine eigenen Schlüsselwörter "getFunk, setFunk, Pruefen" setze ich so ein, damit ich die Methodennamen nicht noch ein weiteres mal schreiben muss. Die Schlüsselwörter benötige ich.
Wenn ich nochmal etwas schärfer nachdenke, müssten Get -und Set Methoden nicht im JavaDoc auftauchen.

Die anderen Methoden werde ich weiterhin wie gehabt Dokumentieren und auch die angesprochenen Probleme und der Vereinheitlichung arbeiten
(Application/pdf, text/plain,...)
Ich denke das könnte ein guter Weg sein.
 
Zuletzt bearbeitet:
Thema: 

Was sollte man ins JavaDoc implementieren??

Passende Stellenanzeigen aus deiner Region:
Anzeige

Neue Themen

Anzeige

Anzeige
Oben