[Javadoc] Tutorial für die Auswertung des docs

[Bozdag]

Hi,

kennt jemand vielleicht eine gute Quelle/Tutorial/etc. die beschreibt, wie man ein Javadoc auswerten/interpretieren kann?

Ich habe einen source code vorliegen der javadoc tags enthält, kann aber mit dem Javadoc wenig anfangen, weil ich (momentan) kaum draus schlau werde.

Daaanke!

 

[agentone]

Die Java-Doc-Kommentare sind dazu da, automatisiert mithilfe von javadoc.exe eine Dokumentation im HTML-Format zu erstellen. Als Programmierer kann man zu jeder Methode, Klasse, Parameter und Rückgabewert eine Beschreibung hinzufügen, damit andere Programmierer das Programm nachvollziehen können.

 

[maki]

Wobei es eigentlich keinen Sinn macht, JavaDoc für private Methoden zu schreiben

 

[agentone]

Ich denke hier Javadoc ? Wikipedia findest du das Wichtigste.

 

[Tomate_Salat]

Wobei es eigentlich keinen Sinn macht, JavaDoc für private Methoden zu schreiben

Und wenn du im Team bist und ein anderer Entwickler iwie mit der private Methode arbeiten muss, er sie aber nicht selbst geschrieben hat ;-). Muss ja nicht immer ein 20-zeiler sein, aber ein kleines Kommentar am Rande bringt niemanden um *meine Meinung*

 

[agentone]

iwie mit der private Methode arbeiten muss

Normalerweise teilt man sich doch die Klassen auf, und kommuniziert über Interfaces miteinander. Allerdings kann es trotzdem nicht schaden, kurz zu beschreiben, was eine private Methode macht.

 

[faetzminator]

Normalerweise teilt man sich doch die Klassen auf, und kommuniziert über Interfaces miteinander. Allerdings kann es trotzdem nicht schaden, kurz zu beschreiben, was eine private Methode macht.

"Normalerweise" würde man das so machen. Wenn man aber 10-20 Entwickler in 50 Projekten hat, welche ab und zu kommen und gehen, dann müssen auch private Methoden kommentiert werden. Abgesehen davon soll man nicht nur für andere, sondern evtl. auch für sich selber kommentieren - das kann aber jeder für sich selber entscheiden.

 

[Tomate_Salat]

Normalerweise teilt man sich doch die Klassen auf...

Ich hoffe doch sehr, du verlässt dich nicht wirklich darauf. Was ist wenn der Entwickler in Urlaub geht oder aus welchen Gründen auch immer den Betrieb verlässt? Dann muss ein anderer daran weiterarbeiten. Und dann hf.

Und wie faetminator schon gesagt hat: es hilft einem auch selber natürlich.

 

[agentone]

Wenn man aber 10-20 Entwickler in 50 Projekten hat, welche ab und zu kommen und gehen

Ich bin mal davon ausgegangen, dass die Entwickler vom Anfang bis zum Ende beim Projekt bleiben. Was natürlich nur in seltenen Fällen der Wirklichkeit entspricht.

es hilft einem auch selber natürlich.

Ja, das hatte ich vergessen zu erwähnen.

... aber ich glaub, wir sind grade wieder mal weit vom eig. Thema abgekommen.

 

[maki]

"Normalerweise" sollten Methoden erkennen lassen, was sie machen.
Sprechende Namen verraten doch schon was sie machen, wenn man wissen will wie sie es machen, muss man sich den Quelltext ansehen.
Private Methoden sind Implementierungsdetails, da braucht/will man doch keine öffentliche Doku.
Quelltextkommentare sind fragwürdig ("Documenting bad code is a waste of time"), bestenfalls.

 

[Tomate_Salat]

"Normalerweise" sollten Methoden erkennen lassen, was sie machen.

Normalerweise, ist aber nicht immer der Fall. Zudem sind noch andere Dinge interessant: welche Exceptions schmeisen sie, was für parameter erwarten sie, informationen zum rückgabewert...
=> D.h. nicht dass ich das zwingend bei JEDER methode machen würde. Man muss unterscheiden.

Private Methoden sind Implementierungsdetails, da braucht/will man doch keine öffentliche Doku.

war nie die Rede von, dass man sie veröffentlichen muss (kann man ja in der JavaDoc einstellen ab welchem lvl dokumentiert werden soll). In eine öffentliche Doku gehört nur das Beschrieben, was für den Anwender interessant ist.

Quelltextkommentare sind fragwürdig ("Documenting bad code is a waste of time"), bestenfalls.

Was ist an denen fragwürdig? A) helfen Sie zum schnelleren einarbeiten B) waren sie übersicht!

 

[maki]

Normalerweise, ist aber nicht immer der Fall. Zudem sind noch andere Dinge interessant: welche Exceptions schmeisen sie, was für parameter erwarten sie, informationen zum rückgabewert...
=> D.h. nicht dass ich das zwingend bei JEDER methode machen würde. Man muss unterscheiden.

Klar, Exceptions sollten dokumentiert werden, aber private Methoden werden ja von protected/public Methoden aufgerufen, wenn ich selber eine private Methode aufrufe, sehe ich mir auch den Quelltext dazu an, wenn ich ihn nicht bereits kenne.

war nie die Rede von, dass man sie veröffentlichen muss (kann man ja in der JavaDoc einstellen ab welchem lvl dokumentiert werden soll). In eine öffentliche Doku gehört nur das Beschrieben, was für den Anwender interessant ist.

JavaDoc generiert keine Doku aus privaten Methoden in der Defaulteinstellung, aus gutem Grunde.

Was ist an denen fragwürdig? A) helfen Sie zum schnelleren einarbeiten B) waren sie übersicht!

Quelltextkommentare gelten als Hinweis für schlechten Code
Kommentare werden vom Compiler nicht verwertet (auch nicht on JavaDoc), da kann Blödsinn drinnstehen, und tut es auch bei Legacy Code, weil man eben nur schnell einen Bug/Feature entfernen/hinzufügen wollte und das Kommentar ignoriert/übersehen hatte.
Kurze, übersichtliche Methoden mit klaren zuständigkeiten und vor allem richtige Namen ersetzen meist 99% der Quellcodekommentare. Manchmal braucht man sie wirklich, zB. für einen komplexen Algorythmen, aber wie hat man diese schon?

Guter Code erklärt sich selbst zum Großteil, dazu gibt es auch schon lange Literatur, aktuell kann ich "Clean Code" von Robert "Uncle Bob" Martin empfehlen. Auch kann man Unittests für seinen Code schreiben, der erklärt dann wie dieser zu verwenden ist (learning tests) und stellt sicher dass er das macht was er soll

 

[Tomate_Salat]

Klar, Exceptions sollten dokumentiert werden, aber private Methoden werden ja von protected/public Methoden aufgerufen, wenn ich selber eine private Methode aufrufe, sehe ich mir auch den Quelltext dazu an, wenn ich ihn nicht bereits kenne.

Ich verweise mal nach oben. Es könnte auch sein, dass die private methode weitere private's aufruft. Klar sollte man sich das iwann mal anschauen wie es funktioniert, aber soetwas kann einen auch aus seinem konzept werfen. 2-3 Sätze zum Thema: was macht diese Methode genau helfen da schon enorm weiter. Du kannst sagen was du willst, das Problem mit unzureichender kommentierung haben wir hier auch im Geschäft und jz teilen wir uns gerade gegenseitig den Zonk zu, wer was dokumentieren darf.

JavaDoc generiert keine Doku aus privaten Methoden in der Defaulteinstellung, aus gutem Grunde.

Hab ich auch nie Behaupted ;-) habe nur gesagt: man kann Einstellen ab welchem level und dass ich auch keine privaten Methoden da reinhauen würde.

Quelltextkommentare gelten als Hinweis für schlechten Code
[...]
Kurze, übersichtliche Methoden mit klaren zuständigkeiten und vor allem richtige Namen ersetzen meist 99% der Quellcodekommentare. Manchmal braucht man sie wirklich, zB. für einen komplexen Algorythmen, aber wie hat man diese schon?

Übelkeit gilt als Hinweis für schwangerschaft...Nene, man muss nich jede Zeile dokumentieren, aber ab und zu eine "Randnotiz" schaded sicherlich nicht.

 

[maki]

Ich verweise mal nach oben. Es könnte auch sein, dass die private methode weitere private's aufruft. Klar sollte man sich das iwann mal anschauen wie es funktioniert, aber soetwas kann einen auch aus seinem konzept werfen. 2-3 Sätze zum Thema: was macht diese Methode genau helfen da schon enorm weiter. Du kannst sagen was du willst, das Problem mit unzureichender kommentierung haben wir hier auch im Geschäft und jz teilen wir uns gerade gegenseitig den Zonk zu, wer was dokumentieren darf.

Da kannst du jetzt sagen was du willst: Unzureichende Doku & schlechten Code macht man mit Quelltextkommentaren nicht wirklich besser, euer Problem beweist das doch.
Habt ihr den die öffentlichen Schnittstellen dokumentiert & einigermassen sauberen Code?

Hab ich auch nie Behaupted habe nur gesagt: man kann Einstellen ab welchem level und dass ich auch keine privaten Methoden da reinhauen würde.

Eben, mir ging es ja in erster Linie um private Methoden, wenne s nicht von JavaDoc ausgewertet wird, brauche ich keine javaDoc kommentare, Quelltextkommentare ersetze ich durch Methoden mit entsprechenden Namen.

Sieh dir mal ein einigermassen sauberes OSS Projekt an, da sind Methoden zwischen 1-5 Zeilen groß, und Klassen im Schnitt 250 zeilen(GUI ist immer anders ). Da verliert man eben nicht so schnell die Übersicht.

Habe das öfters: Ein Kollege sucht verzeifelt in dem Code den er vor 2 Wochen geschrieben hat, hält nix davon Klassen & Methoden kurz & knackig zu halten und aussagekräftige Namen zu verwenden, hat ja ein Kommentar irgendwo....

Persönlich finde ich viele Kommentare in langen Methoden immer sehr witzig, meist reicht es den Code in Methoden aufzubrechen und den Methoden dann die Namen geben die ziemlich genau den Text des Kommentares enthalten (nur ein paar Begriffe weglassen/hinzufügen): Kommentare sind weg, Methoden mit sprechenden Namen sind da. Letztere können dann weiterverwertet werden, indem man neue Klassen erstellt die sehr wenige Aufgaben haben -> die urspüngliche Klasse wird kleiner und hat weniger Aufgaben selber zu erledigen, wird einfacher zu verstehen.

 

[Tomate_Salat]

Da kannst du jetzt sagen was du willst: Unzureichende Doku & schlechten Code macht man mit Quelltextkommentaren nicht wirklich besser

Wann habe ich den dass behaupted oO. Ich bin doch pro Doku und nur weil ich finde Quelltextkommentare sind nützlich heist das nciht, dass ich finde: schlechter code ist damit gelöst

Eben, mir ging es ja in erster Linie um private Methoden, wenne s nicht von JavaDoc ausgewertet wird, brauche ich keine javaDoc kommentare, Quelltextkommentare ersetze ich durch Methoden mit entsprechenden Namen.

wenn das reicht...schön und gut, aber dass tut es eben nicht immer.

Sieh dir mal ein einigermassen sauberes OSS Projekt an, da sind Methoden zwischen 1-5 Zeilen groß, und Klassen im Schnitt 250 zeilen(GUI ist immer anders ). Da verliert man eben nicht so schnell die Übersicht.

Ja gerade an die GUI denke ich aber ;-). Für ein

if(data == null)

setze ich garantiert auch KEINE kommentare.

hält nix davon Klassen & Methoden kurz & knackig zu halten und aussagekräftige Namen zu verwenden, hat ja ein Kommentar irgendwo....

Wie gesagt: ich habe nie behaupted: Kommentare rechtfertigen schlechten code...

 

[maki]

Nun, wenn der Code gut ist, erklärt er sich doch zum Großteil selber (aber nicht unbedingt seine Anwendung), auf jedenfall ist er übersichtlich. Kommentare sind ja dann redundant