Richtige Kommentierung Klassenvariablen

DerwahrePeterderMeter

Neues Mitglied
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

Super-Moderator
Mitarbeiter
Mit @Param beschreibst du nur Methoden-Parameter.

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

insert2020

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

White_Fox

Top Contributor
@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

Top Contributor
@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();
 

White_Fox

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

insert2020

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

kneitzel

Gast
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 ....
 

White_Fox

Top Contributor
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.
 

LimDul

Top Contributor
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.
 

White_Fox

Top Contributor
* 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.
 

LimDul

Top Contributor
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.
 
K

kneitzel

Gast
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

Top Contributor
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.
 
Ähnliche Java Themen
  Titel Forum Antworten Datum
KogoroMori21 Wann ist der richtige Zeitpunkt, um sich Hilfe zu suchen? (Bin Informatik-Student) Java Basics - Anfänger-Themen 10
J Layout Manager, welcher ist der Richtige für mein Program? Java Basics - Anfänger-Themen 1
M Kennt jemand die richtige Lösung? Java Basics - Anfänger-Themen 7
R Ist Java das Richtige für mich? Java Basics - Anfänger-Themen 4
A Java die richtige Programmiersprache für mein Projekt? Java Basics - Anfänger-Themen 1
C Lotto 3, 4, 5, 6 Richtige nach x Ziehungen ermittelt.. Java Basics - Anfänger-Themen 7
G Die richtige Methode aus einer DTO auszurufen Java Basics - Anfänger-Themen 27
E Die richtige Suche in der API Java Basics - Anfänger-Themen 1
L Richtige Reihenfolge der Dateien Java Basics - Anfänger-Themen 5
L Collections Ist eine Arraylist hier das richtige? Java Basics - Anfänger-Themen 12
E Mastermind programmieren, wie den falschen Platz aber richtige Farbe schecken? Java Basics - Anfänger-Themen 23
A OOP Richtige Verwendung von ArrayList und equals Java Basics - Anfänger-Themen 24
I Richtige Java-Version finden? Java Basics - Anfänger-Themen 17
Meeresgott Richtige Dokumentation Java Basics - Anfänger-Themen 1
Meeresgott Richtige Dokumentation Java Basics - Anfänger-Themen 22
P Klassen Richtige Anwendung einer Enum-Klasse Java Basics - Anfänger-Themen 11
H Ist Java überhaupt die richtige Sprache für das Projekt? Java Basics - Anfänger-Themen 8
G Lambda Ausdruck: Welche Methode ist die Richtige? Java Basics - Anfänger-Themen 1
A richtige Kombination aus Werte- und Referenztypen Java Basics - Anfänger-Themen 63
J Erste Schritte Verständnisfrage im Bezug auf das (richtige) Programmieren Java Basics - Anfänger-Themen 5
E Richtige Ausgabe nur mit toString() - Warum? Java Basics - Anfänger-Themen 4
S Das richtige Format für den SOAP Zugriff Java Basics - Anfänger-Themen 0
K Welche Java Version ist die richtige Java Basics - Anfänger-Themen 3
X Methoden Wort aus String löschen und richtige Verschachtelung Java Basics - Anfänger-Themen 17
X Ist Java für mich das richtige? Java Basics - Anfänger-Themen 10
D Simulation von Geburt/Tod und "richtige" Erkennung eines Hindernisses Java Basics - Anfänger-Themen 7
F In ArrayList wird nicht der richtige Wert gespeichert Java Basics - Anfänger-Themen 6
S Richtige String-Variable finden Java Basics - Anfänger-Themen 3
K Richtige Pfadangabe einer Textdatei Java Basics - Anfänger-Themen 7
P Ist Java die richtige Programmiersprache dafür? Java Basics - Anfänger-Themen 29
Dit_ invokeLater | richtige Anwendung Java Basics - Anfänger-Themen 2
L eine richtige anfänger-frage Java Basics - Anfänger-Themen 3
J FileOutputStream richtige Pfadangabe? Java Basics - Anfänger-Themen 8
D Der richtige Layout Manager Java Basics - Anfänger-Themen 8
P Keine richtige Codeabarbeitung?! Java Basics - Anfänger-Themen 9
U Richtige Benutzung der API-Doku Java Basics - Anfänger-Themen 8
G Richtige Syntax für Bruch Java Basics - Anfänger-Themen 12
N Anfängerfrage richtige Syntax und Frage zu Vector Java Basics - Anfänger-Themen 7
G Polymorphismus und die richtige Anwendung Java Basics - Anfänger-Themen 6
B Ist Java das richtige für mich? Java Basics - Anfänger-Themen 12
W Java das richtige? Java Basics - Anfänger-Themen 9
L JTabbedPane, richtige Übergabe von Tabs Java Basics - Anfänger-Themen 18
M Welche Javaversion ist die Richtige? Java Basics - Anfänger-Themen 14
S Java Games Programieren. Der richtige Weg dorthin. Java Basics - Anfänger-Themen 4
M Java die richtige Sprache? Java Basics - Anfänger-Themen 4
S Web Mining - XML Filter der richtige Anstatz? Java Basics - Anfänger-Themen 2
W Java Web Start das richtige? Java Basics - Anfänger-Themen 11
J Richtige Auagabe in einer *.txt Java Basics - Anfänger-Themen 2
B Ist Java das richtige für folgendes Programm! Java Basics - Anfänger-Themen 2
T Bild drehen + richtige größe berechnen Java Basics - Anfänger-Themen 4
M Richtige Paarungen aus Array ausgeben Java Basics - Anfänger-Themen 2
S richtige antworten [%] ausgabe Java Basics - Anfänger-Themen 7
bernd Richtige Pfadangabe für das Kopieren von Dateien Java Basics - Anfänger-Themen 10
A Java wirklich das richtige? Java Basics - Anfänger-Themen 20
B Paar richtige Anfängerfragen Java Basics - Anfänger-Themen 7
Edin Kommentierung von Methoden auf Deutsch oder Englisch? Java Basics - Anfänger-Themen 5
G Frage zu Kommentierung Java Basics - Anfänger-Themen 9
W Unterschiede bei Zugriff auf Objekt und Klassenvariablen über einen Getter? Java Basics - Anfänger-Themen 2
KogoroMori21 Objektvariablen, Klassenvariablen, Instanzvariablen Java Basics - Anfänger-Themen 1
Z private Klassenvariablen Java Basics - Anfänger-Themen 8
N Klassenvariablen zurücksetzen Java Basics - Anfänger-Themen 4
G Klassenvariablen & Instanzvariablen Java Basics - Anfänger-Themen 4
J Variablen Unterschied zwischen lokalen-, Instanz-, Klassenvariablen Java Basics - Anfänger-Themen 6
N Vererbung Best Practice: Verfeinerte Klassenvariablen in Unterklasse Java Basics - Anfänger-Themen 5
D Klassenvariablen standardmäßig private oder public? Java Basics - Anfänger-Themen 2
S Initialisierung von Klassenvariablen Java Basics - Anfänger-Themen 7
A Klassenvariablen zusammen fassen Java Basics - Anfänger-Themen 5
G Frage zu Fields - Klassenvariablen Java Basics - Anfänger-Themen 9
A Klassenvariablen Referenz auf ein Objekt Java Basics - Anfänger-Themen 18
M Variablen Gültigkeit von Klassenvariablen bei Vererbung? Java Basics - Anfänger-Themen 4
J Klassenvariablen lesen Java Basics - Anfänger-Themen 13
B Datentypen Klassenvariablen Java Basics - Anfänger-Themen 2
G OOP Verständisfrage zu Klassenvariablen Java Basics - Anfänger-Themen 5
C Klassenvariablen und Klassenmethoden Java Basics - Anfänger-Themen 17
J Problem mit inneren Klassen und Klassenvariablen Java Basics - Anfänger-Themen 11
G Sollte man Klassenvariablen als final deklarieren? Java Basics - Anfänger-Themen 3
X Zugriff auf Klassenvariablen NUR mit get/set Methoden? Java Basics - Anfänger-Themen 8
W Klassenvariablen und Werte ausgeben Java Basics - Anfänger-Themen 2
D Globale Klassenvariablen. Java Basics - Anfänger-Themen 12
7 Lokale Variablen, Klassenvariablen, Instanzvariablen Java Basics - Anfänger-Themen 15
H Klassenvariablen,methoden Java Basics - Anfänger-Themen 7
M Zugriff auf Klassenvariablen Java Basics - Anfänger-Themen 8

Ähnliche Java Themen

Neue Themen


Oben