Wie sehen gute JavaDoc-Kommentare aus?

[bröggle]

Ich würde evtl eine Klasse veröffentlichen und will dazu einen Java-Doc generieren.


Auf welche Dinge muss man dabei achten?
Was muss es beinhalten?
Deutsch oder Englisch?
Hat jemand ein gutes Beispiel?


^-^

 

[Roar]

du kannst dir ja mal due sourcecodes von der J2SE angucken. aber:

Der Doc-Kommentar für eine Methode sollte kurz den Vertrag zwischen der Methode und ihrem Client beschreiben.

de facto solltest du da rein schreiben was die methode genau macht, was passieren kann, welche exceptions aus welchen gründen geworfen werden, welche parameter übergeben werden sollen etc.

wie gesagt: http://javaresearch.gro.clinux.org/jdk140/java/lang/String.java.html
ist bestimmt n guter anhaltspunkt.

 

[Beni]

Da ich zu denen gehöre, die auch mal 50% der Zeilen mit Kommentar füllen, erlaube ich mir, zu antworten :wink:

Auf welche Dinge muss man dabei achten?
Was muss es beinhalten?

- Ganz wichtig: der spätere User weiss nicht, wie das alles intern funktioniert, und er muss es auch nicht wissen. Also beschreibe wirklich jede Methode, und jede Variable, für was sie gut ist. Lieber einmal zu viel, als einmal zu wenig Text.
- Ein oder zwei kleine Beispiele sind einen nette Hilfe, besonders wenn die Verwendung der Klasse "schwierig" ist.
- Der erste Satz (alles vor dem ersten . ) bei einer Methoden-Beschreibung wird in die Übersicht gesetzt. Also sollte der erste Satz sehr viel über die Methode aussagen.
- Es lohnt sich auch die Java-Doc-Tags wie
, <code>, @link, @see etc. zu benutzen. Das macht die Hilfe interaktiver.
- Rechtschreibfehler sind ärgerlich...
- Und dummer Blabla wie, "Diese Klasse schrieb ich um 9:00 Uhr morgens" haben nichts in einer Doku verloren.

Deutsch oder Englisch?

Was ist dein Zielpublikum?

Hat jemand ein gutes Beispiel?

klar, hier :wink:

mfg Beni

 

[Roar]

Da ich zu denen gehöre, die auch mal 50% der Zeilen mit Kommentar füllen, erlaube ich mir, zu antworten :wink:

oh ja :-/

- Und dummer Blabla wie, "Diese Klasse schrieb ich um 9:00 Uhr morgens" haben nichts in einer Doku verloren.

mist jetzt muss ich wieder alles ändern :lol:

achja: hier steht auch noch was: http://java.sun.com/j2se/javadoc/
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

 

[bygones]

auch auf unsinnige Kommentare verzichten....

/**
  * Returns the number of Results
  */
public int getNumberOfResults() {
....
}

Das bringt nichts - eher erklären was für results, warum und wie....
oder in einer Methode

// i wird um eins erhöht
i++;

 

[Guest]

/** 
  * Returns the number of Results ...weiter was die methode genau macht
  *
  * @return int Wert der die Anzahl der Ergebnisse darstellt
  */ 
public int getNumberOfResults() { 
.... 
}

sollte mann noch einen übergabe parameter haben sollte @param net vergessen werden ebenso wenn nötig
@throws

 

[thE_29]

der JBuilder macht dir wenn du über einen Funktionskopf

/** und dann Enter drückst das halt automatisch mit @param @return

musst nur noch hinschreiben was und wie

Wichtige als Kommentare ist aber auch ein schön strutkturierte Code, gibt es anweisungsteile die zwischen 2-3mal oder höher vorkommen, solltest du dir schon eine eigene Funktion schreiben!

Desweiteren sind auch Einrückungen wichtig und benenn die Variablen so wie der Typ

Bsp.: int iCounter; long lValue; String strName; boolean bErg; double dWert; usw

so weißt du wenn du nachher eine Variable ansiehst, gleich den Datentyp

und verwende ja nie (gibts das in java überhaupt) gotos :lol:

 

[Beni]

Bsp.: int iCounter; long lValue; String strName; boolean bErg; double dWert

Wähle gleich die Namen so geschickt, dass du nicht mal mehr den Typ angeben musst! Wenn Du in einer Klasse den Überblick über die Variablen verlierst, kannst du sowieso gleich von vorne beginnen. :wink:

P.S. es gibt das Schlüsselwort goto, aber es kann nicht verwendet werden.

 

[thE_29]

naja, ich red net von so kleinen Programmen wo die vielleicht 10 Variablen hast

aber wenn du in dem Programm in Zeile 3000 aufeinmal eine Variable siehst die nur help heißt, wäre es halt super das du gleich beim Hinsehen erkennen kannst, welche Variable das ist!

Außerdem kannst da so schnell keine Verwechslung haben

 

[AlArenal]

naja, ich red net von so kleinen Programmen wo die vielleicht 10 Variablen hast

aber wenn du in dem Programm in Zeile 3000 aufeinmal eine Variable siehst die nur help heißt, wäre es halt super das du gleich beim Hinsehen erkennen kannst, welche Variable das ist!

Außerdem kannst da so schnell keine Verwechslung haben

Das funktioniert m.E. so nicht. Neben elementaren Datentypen gibts im Paket java.util noch Hashtables, Hashmaps, Stacks, Vectoren, ... Dann gibts natürlich noch reichlich Instanzen eigener und importierter Klassen, da wirst du mit solch einem Namensschema nicht weit kommen.

Wenn ich eine Variable "help" habe und nicht weiß wozu sie gut ist, habe ich grundsätzlich ein Problem, ob an Zeile 30 oder 3000. Meine Variablennamen beinhalten keinen Hinweis auf den Datentyp, es sei denn ich muss aus irgendwelchen Gründen mal lokale Variablen gleich benennen, weil ich vielleicht gerade Daten in einen anderen Typen überführen und beide parallel benutzen muss. Zur Not drücke ich in meinem JBuilder hinter der Variable auf "." und bekome ein Popup das mit dem Typ der variable (z.B. java.lang.String) überschrieben ist.

Irgendwas haben sich schlaue Leute, die den Kram selbst benutzen, dabei gedacht, als sie die IDEs entwickelten.

Und wenn ich mal auf was stoße, was ich nicht gleich kapiere, sollte ich statt über ein Namensgebungsschema mal besser über einen Kommentar nachdenken. Der sagt nämlich mal mehr aus aus ein paar vorangestellte Buchstaben.

 

[thE_29]

ich red ja auch net von Programmiersprachenabhängige Datentypen (wie Hashmaps, usw)

Hab die Standardtype gemeint, wie int, float, double!

Außerdem zwing ich dich ja net das du es so benennst, aber du kannst sicherlich net sagen, wenn du im Programm aufeinmal einen Variable siehst die iWert heißt und du sofort weißt, aha, das ist int, dass das Schlecht ist!

Und deswegen bringen sinnvolle Namen immer was, so würd ich die Variable auch immer so benennen was sie halt machen und nicht String franz; oder int b;

außer in Schleifen

Variablen sollten wenn du nicht zu faul bist sie so zu benennen, etwas über den Datentyp und die Funktionalität aussagen und wenn du sagst das sei Blödsinn, dann bin ich anderer Meinung als du



PS.: Ich bin Softwareentwickler und ich bin froh wenn ich in Codes die nicht von mir sind, ich beim Namen von einer Variable sehen kann, was das für ein Datentyp oder zumindest sehen kann wozu der gut ist!

Es schaut kein Schwanz auf die kommentare, glaub mir, ich seh jeden Tag ca. 2000 neue Sourcezeilen die nicht von mir sind und ich muss mich auch schnell auskennen
Da les ich nicht ein halbes Jahr Kommentare durch (wenn sie überhaupt existieren!)