Wie kommentiert ihr?

[Ein Programmierer]

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

[-fricky-]

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.

[Ein Programmierer]

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!

[loks]

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.

[-fricky-]

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

[-fricky-]

asc schrieb:

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.

schon richtig, aber manchmal gibts switch/case-anweisungen die ganz schön lang sein können. da ist so'n kommentar */* end of switch(...) / gar nicht so verkehrt.

[Knuddlbaer]

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

z.B. die Realität wie Praxis oder Wirtschaftlichkeit - manchmal auch einfach switch Statements.

[byto]

-fricky- schrieb:

asc schrieb:

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.

schon richtig, aber manchmal gibts switch/case-anweisungen die ganz schön lang sein können. da ist so'n kommentar */* end of switch(...) / gar nicht so verkehrt.

Wo wir wieder beim schlechten Stil wären...

[-fricky-]

byto schrieb:

Wo wir wieder beim schlechten Stil wären...

was tust du denn z.b. gegen einem switch mit 30 cases?

[nosongnornoob]

by the hammer

[SideWinder]

Gibt verschiedene Möglichkeiten, zB:

methods[case].invoke();

MfG SideWinder