Wie kommentiert ihr?

Die Frage sollte evt. besser lauten "Wie kommentiert und dokumentiert ihr?".
Dass man komplexere Codeteile und Funktionen kommentiert bzw. dokumentiert ist klar.

Aber was macht ihr bei folgendem?

int getSize();

Ich schreibe dennoch ein Kommentar dazu:

/**
 * @return Returns the size.
 */

Der Grund ist einfach: da der Kommentar so einfach ist wie die Funktion aussieht, kann der Benutzer davon ausgehen, dass die Funktion wirklich nichts anderes macht und gefahrlos benutzt werden kann, ohne Seiteneffekte befürchten zu müssen.
Manchmal nerven diese Kommentare natürlich, aber da muss man halt durch.
Außerdem erwähne ich auf der Titelseite der Doku/in der Readme, dass solche Kommentare genau das aussagen.

eine gscheite ide macht solche einfachen kommentare für die doku schon von selber, daher: ja, ich machs auch so

Blue-Tiger

Ein Programmierer schrieb:

Ich schreibe dennoch ein Kommentar dazu:
/**
 * @return Returns the size.
 */
Der Grund ist einfach: da der Kommentar so einfach ist wie die Funktion aussieht, kann der Benutzer davon ausgehen, dass die Funktion wirklich nichts anderes macht und gefahrlos benutzt werden kann, ohne Seiteneffekte befürchten zu müssen.

Wenn die Funktion "getSize()" heisst, geh ich davon aus, dass sie das macht, nicht mehr, nicht weniger. Dazu brauch ich keinen Kommentar. Ein Kommentar kommt da nur hin, wenn es Seiteneffekte oder sonstig erwaehnenswertes gibt. Aber wozu den "Normalfall" extra ausfuehrlich dokumentieren?
Solche Kommentare halt ich fuer komplett sinnlos. Der Name ist sprechend genug. Und in der Regel steht im Kommentar genau das selbe wie im Funktionsnamen. In der Regel ist in dem Fall der Kommentar fast gleich lang wie der eigentliche getter/setter. Das macht sich IMO im Quellcode einfach schlecht, weils mich im Lesefluss stoert (ich muss vom "Kommentarmode" in den "Quellcodemode" umschalten wenn ich mich so durch den Source hangle). Und in Doxygen/Javadoc-generierten Seiten brauch ich das auch nicht.

Manchmal nerven diese Kommentare natürlich, aber da muss man halt durch.
Außerdem erwähne ich auf der Titelseite der Doku/in der Readme, dass solche Kommentare genau das aussagen.

*g* Du nennst die Funktion also "get Size", der Kommentar dazu sagt nochmal, dass das die Groesse zurueckliefert und ausserdem steht in der Dokumentation auch nochmal, dass wenn die Funktion "getSize" heisst und der Kommentar aussagt, dass sie nur die Groesse zurueckliefert, dann liefert die Funktion nur die Groesse zurueck?

Nicht ganz, wenn ich die Funktion nicht kommentiert habe, dann kann es ja auch sein, dass ich es vergessen habe. Wenn ein Kommentar dabei steht, dann ist klar, dass ich das nicht habe.

ich kommentiere grundsätzlich alle öffentlichen methoden. selbst wenn der methodenname mehr als eindeutig erscheint, macht ein kommentar es halt nochmal unumstößlich fest.

rüdiger

Ein Programmierer schrieb:

Aber was macht ihr bei folgendem?
int getSize();

Hmm, bei der Funktion würde ich dokumentieren, warum sie nicht konstant ist und auch noch einen Vorzeichenbehafteten Typ zurück gibt, obwohl längen Angaben doch eindeutig Vorzeichenlos sind.

rüdiger schrieb:

Ein Programmierer schrieb:
Aber was macht ihr bei folgendem?
int getSize();
Hmm, bei der Funktion würde ich dokumentieren, warum sie nicht konstant ist und auch noch einen Vorzeichenbehafteten Typ zurück gibt, obwohl längen Angaben doch eindeutig Vorzeichenlos sind.

Du meinst also in C++?

tntnet

Kommentare sollten nicht das enthalten, was das Programm tut. Das sieht man im Code. Kommentare sollten erklären, warum man es tut. Kommentare können falsch sein - der Code irrt nicht. Zu oft sehe ich Code, der zwar fleissig kommentiert ist, aber der Kommentar mit dem Code nichts zu tun hat, da der Block von irgendwo her kopiert worden ist.

Also meine Programme sind sehr sparsam kommentiert. Ich bemühe mich um sprechende Namen, wie z. B. "getSize()". Und wenn die Methode const ist und ein unsigned liefert (wie Rüdiger vorschlägt ), dann ist jeder Kommentar überflüssig. Warum die Grösse zurückgeliefert wird, braucht sicher nicht kommentiert zu werden. Und wenn aus der Klasse nicht hervorgeht, welche Grösse zurück geliefert wird, scheint die Klasse mehr als eine Aufgabe zu haben und sollte getrennt werden. Oder die Methode sollte umbenannt werden, wie z. B. getElementCount() oder getOuterSize(), so daß sie eindeutig wird.

muemmel

Hi,

Stroustrup schrieb in seinen Tipps:

"Halten sie Kommentare knackig."

Der einzige Kommentar, der immer aktuell ist ist der Quelltext. Der sollte sich wie eine Beschreibung des programms lesen, also sprechende Variablen-, Klassen- und Funktionsnamen.

Kommentieren nur, was NICHT aus dem Quelltext hervorgeht.

Gruß Mümmel

Shade Of Mine

euch ist schon klar dass
/**
* @return Returns the size.
*/

kein Kommentar sondern eine Dokumentation ist. Der Unterschied ist klein aber relevant: Dokumentationen müssen auch das logische beschreiben, denn wäre ja doof wenn ich eine Funktion wie getLength suche, sie aber nicht finde weil sie nicht dokumentiert ist...

PS:
Die Beschreiben vom return wert ist aber hier sehr schlecht. es müsste noch gesagt werden welche größe returned wird. uU will man eher sagen "returns the number of objects" oder etwas dergleichen - je nachdem was getSize jetzt liefert.

immer daran denken dass diese dokumentation ja durchsuchbar sein soll...

asc

muemmel schrieb:

Kommentieren nur, was NICHT aus dem Quelltext hervorgeht.

Zum Teil gebe ich dir Recht, im Falle von Speziellen Sprachen (z.B. C#) oder Situationen aber wiederum nicht.

a) Wenn man mit einem Dokumentierungstool (z.B. Doxygen) arbeitet kann man verhindern das man Kommentare vergisst in dem man Kommentare erzwingt. Nachteil: Dann muss man dies auch konsistent für alle Funktionen machen. Hier muss einfach abwägen.
b) In .Net gibt es spezielle XML-Komentare die, die Ausgabe von Intellisense deutlich aufbohren. Hier verwende ich alleine aus Konsistenzgründen auch durchgängig Kommentare.
c) In Fällen in denen der Code einheitlich in einer Sprache, die Kommentare aber in einer anderen geschrieben sind, macht es auch Sinn um Projektweite einheitliche Übersetzungen zu unterstützen (z.B. englischer Code, deutscher Kommentar).

cu André
P.S: Wenn ich komplett Kommentiere sind bei mir immer mindestens alle folgenden Angaben definiert: Allgemeine Beschreibung, Parameter, Rückgabewert
Dies ist unabhängig vom Kommentarstil (Doxygen, .Net...).

Ein Programmierer schrieb:

Aber was macht ihr bei folgendem?
int getSize();

ich würde noch hinschreiben, was 'size' eigentlich bedeutet. oft ist es nicht ganz offensichtlich. was ist z.b. die 'size' eines käsekuchens? die höhe? anzahl vorhandener stücke? das volumen?

rüdiger schrieb:

Hmm, bei der Funktion würde ich dokumentieren, warum sie nicht konstant ist und auch noch einen Vorzeichenbehafteten Typ zurück gibt, obwohl längen Angaben doch eindeutig Vorzeichenlos sind.

warum konstant, wenn 'size' veränderlich ist?
das mit dem vorzeichen würde ich aber auch so sehen. ausser man hat eine 'size' die auch negativ sein kann. sowas ist zwar selten, aber nicht völlig unmöglich.

byto

tntnet schrieb:

Kommentare sollten nicht das enthalten, was das Programm tut. Das sieht man im Code.

Ich möchte mir aber nicht jedes Mal erst den Code angucken, um zu wissen, was eine Methode tut, wenn ich sie an einer beliebigen Stelle aufrufe.

Wie Shade richtig festgestellt hat ging es mir eigentlich mehr um das Dokumentieren in meinem Beispiel. Außerdem könnt ihr mal das mit unsigned und const lassen, ich habe das bewusst so geschrieben, damit der Code nicht nur in C++ gültig ist, sondern auch in Java.

Shade du hast völlig recht, einfach "returns the size" ist eher ungeschickt formuliert, besser wäre hier wirklich hinzuschreiben was zurückgeliefert wird.

Schreibt ihr als noch den Aufwand in eure Dokumentation? Und wie stets mit dem Speicherverbrauch? Also ich meine hier keine konkreten Werte, sondern ein O(1), oder vllt. mit etwas mehr Information O(3n).

byto

Nicht mehr dokumentieren als zum groben Verständnis nötig. Schließlich muss man die Doku beim Code-Refactoring immer mitpflegen. Je kürzer die Dokumentation, umso leichter fällt das. Je leichter es fällt, umso häufiger wirds gemacht.

Und nichts ist schlimmer, als eine veraltete (falsche) Dokumentation. Die ist dann nämlich schlechter als gar keine Doku weil irreführend!

Der Fehler des OP ist es, Kommentierung und Dokumentation durcheinanderzuwerfen.

Dokumentation sollte Lückenlos sein, also auch so eine Trivialfunktion wie GetSize() muss Dokumentiert sein, auch wenn es offensichtlich ist. Grund: In der Dokumentation erscheint _kein_ Sourcecode. Das Argument: "der Sourcecode erklärts" greift hier also nicht.

Nebenbei: Der Dokumentationseintrag sollte beschreiben was die Funktion machen _soll_. Wenn die GetSize() Funktion dokumentiert ist als: Ermittel die Größe, in Wirklihckeit aber etwas ganz anderes liefert ist es leichter diesen Bug zu finden, besonders wenn der Tester nicht der Programmierer ist. Die Dokumentation kann man hier betrachten als: "Das wollte ich machen" und der Sourcecode ist dann "Das habe ich gemacht". Wenn die beiden nicht übereinstimmen liegt ein logischer Fehler im Code vor. Hier kommt man schnell in eine Zwickmühle: Man selber erkennt einen Logikfehler oft nciht eben weil man ihn für richtig hält. Ein anderer wiederum kann den Logikfehler nicht erkennen weil er nicht die Gedanken des Programmierers lesen und damit wissen kann was der eigendlich machen wollte.

Ganz anders sieht das mit Kommentierung aus. Hierauf bezieht sich auch das Zitat von Stroustrup.

Kommentierung im Stil:

int index;  // int varible mit Namen index

object.GetSize()  // Get the size form object

int main() // main-function
{
} // end main-function

etc sind einfach nur Schwachsinn und sogar Kontroproduktiv, weil man so unter 100 Zeilen sinnlosem Kommentar den einen wichtigen übersieht.

Sowas sieht man gerne in Tutorials (wo der Nutzen diskutabel ist) und Anfänger übernehmen diesen Stil dann gern.

Bei Kommentierung gilt wirklich: Nur kommentieren was nicht offensichtlich ist.

Blue-Tiger

byto schrieb:

tntnet schrieb:

Kommentare sollten nicht das enthalten, was das Programm tut. Das sieht man im Code.

Ich möchte mir aber nicht jedes Mal erst den Code angucken, um zu wissen, was eine Methode tut, wenn ich sie an einer beliebigen Stelle aufrufe.

Deshalb gibts sprechende Funktionsnamen

Schreibt ihr als noch den Aufwand in eure Dokumentation? Und wie stets mit dem Speicherverbrauch? Also ich meine hier keine konkreten Werte, sondern ein O(1), oder vllt. mit etwas mehr Information O(3n).

Wenns relevant ist ist schon, ja. Aber dass mein log2(x)-Hilfsfunktion in O(log n) statt in O(n) (mit n Anzahl Bits von x) arbeitet, interessiert z. B. niemand ( es sei denn ich schreibe eine Mathe-Library).
Aber dass mein findSimilarFiles(File f, Directory d) im "FindeDoppelteMP3s"-Programm in O(n*n) der Files im gegebenen Verzeichnis arbeitet, ist erwaehnenswert. Aber mehr als die Komplexitaetsklasse gibts da auch nicht.

loks schrieb:

Kommentierung im Stil:
...
} // end main-function
etc sind einfach nur Schwachsinn und sogar Kontroproduktiv

kommt drauf an, wie länglich deine 'main-function' ist.

asc

-fricky- schrieb:

kommt drauf an, wie länglich deine 'main-function' ist.

Zu große Funktionen deuten immer auf einen schlechten Stil hin. Funktionen sollten nur so groß sein das man sie noch sinnvoll überblicken und verstehen kann. Daher sehe ich diese Form der Kommentierung eh als Schwachsinn an.

cu André

Shade Of Mine

-fricky- schrieb:

loks schrieb:
Kommentierung im Stil:
...
} // end main-function
etc sind einfach nur Schwachsinn und sogar Kontroproduktiv
kommt drauf an, wie länglich deine 'main-function' ist.

nein. denn dafür hast du eine ide

mal abgesehen davon dass wenn eine funktion ueber mehr als eine seite geht, du andere probleme hast als kommentare...