Richtige Kommentierung Klassenvariablen

  • Themenstarter DerwahrePeterderMeter
  • Beginndatum
Diskutiere Richtige Kommentierung Klassenvariablen im Java Basics - Anfänger-Themen Bereich.
D

DerwahrePeterderMeter

Hallo, hallo liebe Leute des Java-Forums,

kurze Frage: Für eine konforme Kommentierung werden (Konstruktor-)Variablen, die ich von einer Testklasse lade, mit @param bezeichnet, oder? Wie beschreibt man denn Klassenvariablen (static)?

Ich habe einfache Java-Kommentare daneben gehauen, damit das Externe verstehen können. Dr. Google habe ich verwendet, stoße dort jedoch nur auf Anleitungen wie @param zu benutzen ist, nicht aber ob man z.B. üblicherweise auch Klassenvariablen damit beschreiben sollte

Danke und Grüße
Peter
 
mrBrown

mrBrown

Mit @Param beschreibst du nur Methoden-Parameter.

An Felder, egal ob statisch oder nicht, kommt einfach ein ganz normaler Javadoc-Kommentar.
 
I

insert2020

In Variablenbeschreibenden Kommentaren müssen keine Annotationen genutzt werden. Eine Ausnahme können Methodenverlinkungen, etc. sein...
 
W

White_Fox

@mihe7
Naja, bei einer cleveren Benamsung und Struktur bleibt dir ja gar nix anderes übrig. Da sind solch detaillierte Kommentare eher kontraproduktiv, wenn sie bei einer Refaktur vergessen werden.
 
mihe7

mihe7

@mihe7
Naja, bei einer cleveren Benamsung und Struktur bleibt dir ja gar nix anderes übrig. Da sind solch detaillierte Kommentare eher kontraproduktiv, wenn sie bei einer Refaktur vergessen werden.
Noch besser sind Kommentare, die beim Copy & Paste übrig geblieben sind. Die schauen dann z. T. etwa so aus:
Java:
// fals bezahlt...
if (rechnung.status != RechnungStatus.BEZAHLT) {
    ...
}
// auf keinen Fall xy ausführen
xy();
 
W

White_Fox

Heieieiei...und auch noch auf deutsch programmiert... :eek:
Zugegeben, das hab ich auch mal gemacht, mir aber dann doch mal abgewöhnt...
 
mihe7

mihe7

Heieieiei...und auch noch auf deutsch programmiert... :eek:
Zugegeben, das hab ich auch mal gemacht, mir aber dann doch mal abgewöhnt...
Nein, das war jetzt nur der Darstellung halber. Aber man sieht halt, dass da die Kommentare vergessen wurden - und im ersten Moment denkt man sich: WTF?!?
 
W

White_Fox

Also Vorschlag: Auf Kommentare vollständig verzichten, verwirrt ja alles eh nur. :)
 
I

insert2020

Wollt ihr mich vereiern? In der Regel sollte man doch sprechende und wiederauffindbare Variablennamen wählen, dann braucht es keine Kommentare...
 
J

JustNobody

Also ja: Kommentare um Code zu dokumentieren sind eher kontraproduktiv und Code sollte sich selbst beschreiben. Wenn Code durch Kommentare erläutert werden muss, dann ist das ein Zeichen, dass der Code verbessert werden sollte.

Aber hier im Thread geht es um JavaDoc, da ist das Ziel die Generierung von externer Dokumentation. Da wird also Code missbraucht, damit man nicht an zwei Stellen etwas schreiben muss.

Generell kann man sich streiten, ob und wo das Sinn macht.

Wenn man gewisse Tools nicht hat, die Änderungswünsche sauber verknüpfen, dann kann man z.B. vor Änderungen da Hinweise im Code in Kommentaren platzieren. Dann ist klar: an der Stelle wurde etwas wegen Change Request xyz etwas verändert. Die saubere Lösung ist, dass es verknüpft ist, aber wenn man das nicht hat?

Und man muss nur sehen, wie jung da vieles ist. Wann sind welche Punkte aufgekommen? Es gibt auch Projekte, die schon Jahrzehnte alt sind....
Da finden sich dann teilweise Lösungen, die einfach gewählt wurden, weil es gewisse Lösungen noch nicht gab.

Aber man sollte wissen, was es heute so alles gibt und was möglich ist.

Das einfach mal meine kleine Sicht dazu ....
 
W

White_Fox

Reicht es für die externe Dokumentation nicht aus, wenn man die öffentliche Schnittstelle dokumentiert?
Ich schreibe mittlerweile auch bei privaten Methoden Javadocs. Nicht immer, aber immer öfter. Gerade wenn diese Methoden noch andere Methoden aufrufen oder komplexere Dinge erledigen, ist das nicht unbedingt nachteilig. Außerdem kann man das während des Programmierens lesen.

Zumindest im Fall von Javadoc finde ich, das mehr mehr ist.
 
L

LimDul

Ich schreibe mittlerweile auch bei privaten Methoden Javadocs. Nicht immer, aber immer öfter. Gerade wenn diese Methoden noch andere Methoden aufrufen oder komplexere Dinge erledigen, ist das nicht unbedingt nachteilig. Außerdem kann man das während des Programmierens lesen.

Zumindest im Fall von Javadoc finde ich, das mehr mehr ist.
Dem würde ich widersprechen. Probleme mit Javadoc ist:

* Es wird nicht gewartet. Sprich, nach einer genügend großen Zeitspanne und Weiterentwicklungen passt das Javadoc nicht mehr zur Methode. Egal wie sehr man sich das vornimmt. Alleine die Tatsache, dass Refaktorings mit IDE Unterstützung schnell gehen, Javadoc wird dabei nur minimal mit automatisiert angepasst.
* Bei entsprechend kleinen Methoden und vernünftiger Bennung der Methode und der Parameter steht im Javadoc nicht mehr drin.

Für public API ist es definitiv sinnvoll, aber bei privaten Methoden ist Javadoc immer zuerst mal ein Code-Smell, dass diese Methode zu komplex ist.
 
W

White_Fox

* Es wird nicht gewartet. Sprich, nach einer genügend großen Zeitspanne und Weiterentwicklungen passt das Javadoc nicht mehr zur Methode.
Das ist zwar richtig, ich sehe da aber eher den Punkt das man eine Methode erstmal sehr lange Zeit nicht mehr anfasst und sich dann fragt, was man da genau gemacht hat. Oder irgendwelche Besonderheiten, daß im Fall xy null zurückgegeben wird, o.ä.

Ich sah das bis vor einiger Zeit auch noch so, gerne Methoden mit möglichst ausdrucksstarken Bezeichnungen zu verwenden. Allerdings wird das zum Alptraum, wenn man (z.B. beim Debugging) einen kompletten Handlungsstrang mal im Detail ansehen und nachvollziehen will. Jedenfalls ist das mein subjektiver Erkenntnisgewinn der letzten Wochen. Eine Unstimmigkeit über 10 oder 15 Methodenaufrufe (gerne auch über mehrere Klassen verteilt)

Auch für Besonderheiten, Sonderfälle, usw. find ich Notizen in Javadocs vorteilhafter. So etwas merkt man sich nicht, und wo soll es sonst stehen.

Außerdem hast du das Problem, das Doku und Code nach und nach auseinanderlaufen, eigentlich immer. Dieses Problem wird man solange haben, bis der Computer entweder deinen Code versteht und die Doku vollautomatisch vollständig und richtig selber erstellt, oder anhand deiner Doku eine Methode automatisch programmiert.


* Bei entsprechend kleinen Methoden und vernünftiger Bennung der Methode und der Parameter steht im Javadoc nicht mehr drin.
Ja, das ist meistens der Fall. Aber den Fall mein ich ja nicht.
 
L

LimDul

Das ist zwar richtig, ich sehe da aber eher den Punkt das man eine Methode erstmal sehr lange Zeit nicht mehr anfasst und sich dann fragt, was man da genau gemacht hat. Oder irgendwelche Besonderheiten, daß im Fall xy null zurückgegeben wird, o.ä.
Nullable / CheckForNull / NonNull - Annotationen verwenden. Sinnvoller als es im Javadoc zu beschreiben. Kann insbesondere auch von Spotbugs geprüft werden. Ansonsten generell in Methoden Argumente checken und Sonderfälle vermeiden (bzw. ggf. in eigene Methoden auslagern)

Ich sah das bis vor einiger Zeit auch noch so, gerne Methoden mit möglichst ausdrucksstarken Bezeichnungen zu verwenden. Allerdings wird das zum Alptraum, wenn man (z.B. beim Debugging) einen kompletten Handlungsstrang mal im Detail ansehen und nachvollziehen will. Jedenfalls ist das mein subjektiver Erkenntnisgewinn der letzten Wochen. Eine Unstimmigkeit über 10 oder 15 Methodenaufrufe (gerne auch über mehrere Klassen verteilt)
Idealerweise sind die Methoden so klein (kleiner 30 Zeilen Code), das man sie mit einem Blick erfassen kann. Mehr als zwei Ebenen Verschachtelung sollte man auch nach Möglichkeit vermeiden. So verbietet checkstyle standardmäßig verschachtelte Ifs mit mehr als einer Ebene.

Siehe auch: https://dzone.com/articles/rule-30-–-when-method-class-or


Auch für Besonderheiten, Sonderfälle, usw. find ich Notizen in Javadocs vorteilhafter. So etwas merkt man sich nicht, und wo soll es sonst stehen.
Unit-Tests. Da gehören Sonderfälle hin, weil dann ist Sichergestellt, dass der Code auch das im Sonderfall tut. Den genau diese Sonderfälle laufen sehr leicht auseinander, wenn man was anpasst. Ansonsten Methoden so schneiden, dass es möglichst keine Sonderfälle gibt.

Außerdem hast du das Problem, das Doku und Code nach und nach auseinanderlaufen, eigentlich immer. Dieses Problem wird man solange haben, bis der Computer entweder deinen Code versteht und die Doku vollautomatisch vollständig und richtig selber erstellt, oder anhand deiner Doku eine Methode automatisch programmiert.
Deswegen versuchen, alles was man durch Code oder Tools sicherstellen kann, darüber sicherzustellen und nicht durch Doku.

Ja, man kommt nicht immer drumherum. Und alles geht auch nicht über das oben beschriebene. Aber man sollte dran arbeiten, so viel wie möglich automatisiert zu behandeln.
 
J

JustNobody

Reicht es für die externe Dokumentation nicht aus, wenn man die öffentliche Schnittstelle dokumentiert?

Beim Rest gilt was @JustNobody schon geschrieben hat: Guter Code sollte sich selbst dokumentieren.
Es stellt sich immer die Frage, was genau dokumentiert werden soll oder muss.

Um öffentliche API geht es dabei nicht immer. Ich habe in Projekten auch schon einiges mehr dokumentiert.

Es ist immer klar zu definieren:
Was wird wie für wen dokumentiert. Das kann also auch durchaus Businesslogik sein, die aus dem Code ersichtlich wäre, aber eben umgangssprachlich vorliegen muss.

Ich muss aber gestehen, dass wir hier Dinge eher aus dem Code heraus ziehen. Dann haben wir Ressource Dateien aus denen auch Dokumentation generiert wird.
 
mihe7

mihe7

Also Vorschlag: Auf Kommentare vollständig verzichten, verwirrt ja alles eh nur. :)
Ne, nur auf schlechte Kommentare verzichten. Kurz gesagt sind das solche, die den Adressaten des Kommentars keine oder falsche Zusatzinformationen liefern.

Als Gegenbeispiel mal Math.PI: "The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter." Der letzte Halbsatz wäre in einem Projekt grenzwertig (was PI ist, weiß man), ist hier allerdings schon dadurch gerechtfertigt, als dass sich die Doku der Java Plattform an einen riesigen Empfängerkreis richtet. Den ersten Halbsatz dagegen finde ich genial.
 
Thema: 

Richtige Kommentierung Klassenvariablen

Passende Stellenanzeigen aus deiner Region:
Anzeige

Neue Themen

Anzeige

Anzeige
Oben