Kommentare richtig schreiben

[binverwirrt]

Hi,
wie man Kommentare macht weiß ich, doch habe ich in meiner Schule 4 verschiedene Programmierlehrer, jeder sagt mir etwas anderes zu Kommentaren

Hauptsälich sagen sie: (zb)

1. Selbstverstänldiche sachen wo der Methodenname schon genug aussagt braucht keine Kommentare mehr

public void printHaeuser()
{
     for(Häuser h: wohnanlage) 
     { 
         System.out.println(h) 
     }
}

2. Eine kleine Beschreibung die in deutsch (keine java begriffe) geschrieben ist soll IMMER sein, nie wie etwas gemacht wird erkährt, sondern nur was es tut

/**
* Gibt alle vorhandenen Häuser aus.
*/
public void printHaeuser()
{
     for(Häuser h: wohnanlage) 
     { 
         System.out.println(h) 
     }
}

3. Alles java-spezifisch erklähren

/**
* Gibt alle vorhandenen Häuser in der arraylist wohnanlage aus.
*/
public void printHaeuser()
{
     for(Häuser h: wohnanlage) 
     { 
         System.out.println(h) 
     }
}

4. alles

/**
* Gibt alle vorhandenen Häuser in der arraylist wohnanlage aus.
*/
public void printHaeuser()
{
     for(Häuser h: wohnanlage)  //anfang: durchläuft das arraylist wohnanlage und gibt alle häuser aus
     { 
         System.out.println(h) 
     } //ende von ausgabe von wohnanlage
}

Also, das wenn es für MICH geschrieben ist, oder für einen Lehrer (je nach lehrer halt) ich es so oder so machen kann weiss ich, doch wie ist es allgemein (in der berufswelt)?
zb sollte der code ungefähr aus 60% code und 40% kommentaren bestehen habe ich mir sagen lassen (richtiline)

So, hoffe ich konnte es deutlich genug erkähren
danke schonmal

 

[diggaa1984]

Am besten ist es sich gleich an JavaDoc-Convention zu gewöhnen.

Da kannst dir mit Hilfe des Javadoc-tools auch gleich eine passende html-doku draus basteln, die bequem zu lesen ist

 

[Marco13]

Ich find' englisch ja besser :?

 

[diggaa1984]

Ich find' englisch ja besser :?

oder zumindest einheitlich, seh grad da oben ein "printHaeuser" ^^

 

[Murray]

Variante 4 trägt m.E. nicht zum besseren Verständnis bei; die Kommentare innerhalb der Methode beschreiben Selbstverständlichkeiten, die man ohne den Kommentar nicht weniger gut versteht.

An Variante 3 gefällt mir nicht, dass hier ohne Not ein für das Verständnis der Methode irrelevantes Implementierungsdetail (nämlich die Tatsache, dass es sich um eine ArrayList handelt) in den Kommentar gezogen wird - kommt man jetzt auf die Idee, anstelle der ArrayList eine andere Collection zu verwenden, muss man in dieser Methode den Kommentar (aber sonst nichts!) ändern.

Man könnte m.E. ruhig noch erwähnen, wohin ausgegeben wird:

/**
* Gibt alle Häuser der Wohnanlage auf die Standardausgabe aus.
*/
public void printHaeuser() {
     for( Häuser h : wohnanlage) {
         System.out.println( h)
     }
}

 

[musiKk]

1. Alles, was public ist, sollte meiner Meinung nach dokumentiert werden. Ich kanns jedenfalls nicht leiden, Lücken in den Javadoc-Seiten zu haben.
2./3. Bei sowas sollte List oder gar ArrayList nicht erwähnt werden, weil dies Implementationsdetails sind, die den Nutzer des Objekts und dessen Methoden nicht zu interessieren haben.
Implementationsdetails sollten nur selten auftauchen, z. B. wenn es um Performance geht. Was aber interessant ist, ist das, was nun passiert. Wie werden die Häuser geschrieben? Wohin?
4. ist sehr typisch für Programmieranfänger. Das ist jetzt nicht unbedingt abwertend gemeint. Auf lange Sicht gewöhnt man sich das eh ab.

Das mit den 60/40... naja... ich bin jetzt nicht besonders industriegeprägt, sondern großteils eher (noch) akademisch. Kommentare sollten präzis und nicht ausufernd sein. Methoden- und Klassenkommentare im Javadoc-Stil. Mit anderen Kommentaren sehr sparsam umgehen. Als Richtlinie dabei gilt: Nie das in Kommentare schreiben, was gemacht wird (so wie in 4.), sondern warum. Denn, was gemacht wird, steht ja schon im Quelltext. Wenn da ein for(...) steht und rechts vom : ist eine List, dann ist ja klar, dass man über selbige rennt. Solche Kommentare lenken nur ab. Wenn aber etwas gemacht wird, was auf den ersten Anschein nicht ganz klar ist, dann sollte gesagt werden, warum man das doch tut. Ist nicht ganz leicht, da ein Beispiel zu konstruieren. Zumal bei kleinen Beispielprogrammen sowas auch eher nicht auftritt.

Für englisch bin ich persönlich auch.

 

[Wildcard]

3. und 4. sind absoluter Unsinn.
Zunächst musst du unterscheiden zwischen JavaDoc und Kommentaren.
Javadoc sollte bei jeder öffentlichen Methode vorhanden sein. Dort beschreibst du was ein Entwickler der diese Methode verwenden möchte zu erwarten hat.
-Wie die Methode arbeitet
-Erklärung der Parameter (welche Werte sind erlaubt und liefern welche Resultate)
-Beschreibung des zu erwartenden Rückgabewerts (kann zB null zurückgeliefert werden)
-mögliche Exceptions
-links auf ähnliche/weiterführende Methoden
...

Dann noch die Kommentare die dort angebracht werden sollten, wo Erklärungsbedarf besteht (der Code leuchtet nicht sofort ein). In Kommenaren wird immer beschrieben warum etwas getan wird, nicht wie.
Fügst du zB einen Bugfix im Code ein, bietet es sich an die Bugnummer im Quellcode an passender Stelle per Kommentar zu referenzieren, damit sich der interessierte Entwickler näher über den Bug informieren kann.

 

[diggaa1984]

Ich find' englisch ja besser :?

oder zumindest einheitlich, seh grad da oben ein "printHaeuser" ^^ .

EDIT aeh irgendwie grad n fehler vom reload des browsers ... nicht gewollt ^^

 

[didjitalist]

die information, wie eine methode intern arbeitet ist nur dann von belang, wenn genau das diese methode auszeichnet. wenn man also beispielsweise zwei methoden anbietet, die dasselbe leisten, aber unterschiedliche algorithmen verwenden.

ansonsten sollte für alle öffentlichen methoden folgendes kommentiert sein:
- was leistet die methode
- aufzählung von nötigen vorbedingungen zur korrekten funktionsweise der methode, wenn sie nötig sind
- wofür sind die parameter da, welche werte sind erlaubt, führen unerlaubte werte zu exceptions?
- was wird zurückgeliefert, ist das objekt eine referenz auf interna? kann null geliefert werden?
- weitere mögliche exceptions, die bei gültigen (!) parameterwerten auftreten können (laufzeit fehler)

für die oben genannte methode sähe ein kommentar unter diesen umständen ungefähr so aus:

/** 
* Gibt alle Häuser dieser Wohnanlage auf die Standardausgabe {@link System.out} aus.
*
* @see Häuser#toString()
*/ 
public void printHaeuser() { 
     for( Häuser h : wohnanlage) { 
         System.out.println( h) 
     } 
}

sollte es möglich sein, dass 'wohnanlage' null ist, muss eine NullPointerException erwähnt werden. z.b. wenn das feld erst initialisert wird, wenn das erste haus hinzugefügt wird. es macht aber durchaus sinn, diesen zustand einfach zu unterbinden, indem wohnanlage auf jeden fall immer initialisiert ist.