Programm richtig kommentieren

[St.Pauli]

Luckie hat vollkommen recht. Nicht kommentieren was man macht, sondern warum und immer abwägen, ob ein Kommentar an dieser oder jener Stelle erforderlich ist oder nicht. Durch einen übersichtlichen Code und eine gute Namensgebung kann man sich aber schon ein paar Kommentare ersparen.

@Luckie:

Zitat von Luckie:

Ich kommentiere immer so wenig wie möglich, so viel wie nötig. Und das:

Delphi-Quellcode:

//x incrementieren 
x := x + 1;

würde ich nicht kommentieren. Wozu? Was bringt e, Leser der Kommentar an zusätzlichen Informationen? Nichts. Man sollte nicht kommentieren wa sman macht, das sehe ich selber am Code, sondern warum man etwas macht.

Delphi-Quellcode:

// Speicher wieder freigeben
FreeMem(Buffer);

[Luckie]

Ich habe doch erklärt, warum ich diese Zeilen kommentiert habe.

[Elvis]

Zitat von Luckie:

Man sollte nicht kommentieren wa sman macht, das sehe ich selber am Code, sondern warum man etwas macht. Aktuelles Beispiel aus meinen String-DLL Artikel:
...
Der Kommentar in Zeile 48 sagt warum ich dort diese Funktion aufrufe. Aus der Dokumentation würde hervorgehen, dass der Funktion im zweiten Parameter ein Buffer übergeben wird, in dem das Ergebnis landet. Und im Kommentar erkläre ich warum ich die Funktion erstmal mit nil aufrufe. Damit wird dann auch der Rest des Codes klar.

Naja, das ist eher ein schlechtes Beispiel.
Hättest du die Funktion nicht zu einer nichtssagend benannten eierlegenden Wollmilchsau gemacht, wäre klar gewesen was passiert.
Du hättest dann nämlcih einen Funktionszeiger namens getBufferSize und einen namens fillBuffer gehabt.
Natürlich sind auch andere Namen möglich, aber IMO wäre dann in dem Code nicht ein Kommentar nötig.
Es gibt einfach keine Fallstricke. Naja bis auf die Tatsache, dass man in Delphi nicht sehen kann wann ein Parameter ein var-Parameter ist (bei dir nicht der Fall).

[gsh]

Ich kommentiere eigentlich nie einzelne Befehl (höchstens selbst geschriebene Funktion)

Was ich eher komentiere sind bereiche also z.b.

Delphi-Quellcode:

{Berechnungen beginnen}
x := y+1;
..
..
y := x;
{Ergebniss ausgeben}
Label1.Caption := inttostr(x);
Label2.Caption := inttostr(y);
Label3.Caption := inttostr(z);

[Luckie]

Nein, wenn dann hätte die Funktion ConCatString heißen müssen oder so. Und da wäre der Kommentar auch gerechtfertigt gewesen.

[mkinzler]

Lieber ein Kommentar zu viel, als einen zu wenig.

[Zacherl]

Zitat von Luckie:

Ich kommentiere immer so wenig wie möglich, so viel wie nötig. Und das:

Delphi-Quellcode:

//x incrementieren 
x := x + 1;

würde ich nicht kommentieren. Wozu? Was bringt e, Leser der Kommentar an zusätzlichen Informationen? Nichts.

Normal würde ich sowas auch nicht kommentieren War ja nur als Beispiel gedacht ...

[Kevin]

Richtig oder falsch kommentieren ist auf jeden Fall auch relativ. Und wer jemals einen Quellcode von jemand anderem weiterentwickeln "musste", ist für jeden noch so kleinen Kommentar dankbar.

[negaH]

Lieber einen Kommentar einsparen weil der Source sich absolut selbst erklärt !

Frage: Worin besteht eigentlich der Unterschied zwischen einem Sourcecode und einem Kommentar ? wenn wir davon ausgehen können das wir heute Sourcecode schreiben können der sich vollkommen selbst erklärt ?

Ein Kommentar soll garnichts zum Source direkt erklären sondern höchstens

1. Referenzen zum verwendeten Algorithmus im Source liefern, wie Links, Bücher etc.pp.
2. wichtiges und eventuell fehlendes Background Wissen das nicht im Source ersichtlich ist nachliefern

Ein Kommentar wird damit zu inaktivem Source = Quelle, weil wir mit der heutigen Programmierspache dieses Wissen nicht direkt als aktiven Source ausdrücken können. Wobei ja exakt das in neueren Sprachen, zb. eben aus dem Konzept der VCL mit ihren Komponneten und dem visuellen RAD ja schon verbessert hat. Just my 2 cent

Gruß Hagen

[Elvis]

Zitat von Kevin:

Richtig oder falsch kommentieren ist auf jeden Fall auch relativ. Und wer jemals einen Quellcode von jemand anderem weiterentwickeln "musste", ist für jeden noch so kleinen Kommentar dankbar.

Kommt immer darauf an wieviel 3rd-Party Libs oder selbstgeschriebene funktionen im Spiel sind.
In Luckies Beispiel wird eine Funktion zum Konkatinieren zweier Strings benutzt, die auch noch die resultierende Länge zurückgibt.
Sie wurde a)nur nichtssagend "func1" genannt und b) 2-mal mit komplett unterschiedlichen Absichten benutzt. Einmal um die Länge zu bekommen, ein anderes mal um tatsächlich mit den Strings zu arbeiten.
Sowas ist schon vom Prinzip her etwas schief und erfordert deshalb Kommentare.
Code, der keine Fallstricke hat braucht keine Kommentare, da dadurch die schnelle Lesbarkeit einfach sinkt.
Aber Methoden selbst sollten immer eine Summary im Header haben, zumindest wenn sie nix triviales machen.

Nachtrag:@Hagen, jennau!