Wie und wieviel kommentiert Ihr Euren Code

[Luckie]

Ich versuche es auch so, dass der Code von alleine erklärend ist. Eine Versionshistory im Header kann, aber denn noch sinnvoll sein, wenn man den Code weggibt. Die haben dann ja meistens nicht den Verlauf im Repository. Ändere ich bestehenden Code von anderen kommt meist ein:

Delphi-Quellcode:

// MP start
// [Datum, Grund]
...;
...;
...;
// MP ende

in den Code. Dann kann man auf den ersten Blick nachvollziehen wer, was, wo warum geändert hat ohne alte Versionen erst vergleichen zu müssen.

[Benedikt Magnus]

Zitat von Aviator:

Schlimm finde ich aber so Kommentare wie das bei Linux in manchen Konfigurationsdateien zu finden ist. Da wird erst 100 Zeilen Kommentar geschrieben und dann kommt die eigentlich eine (!) Zeile die eine Funktion hat. Das übersieht man dann einfach und wundert sich, wieso nix in der Datei drin steht was etwas bewirken könnte.

Naja, das hat aber schon seinen Sinn. Denn diese hundert Zeilen beschreiben z.B. genau, was neben dieser einen folgenden Zeile noch alles möglich ist, wie es funktioniert und wann was sinnvoll ist. Stell dir vor, du kannst in einem Aufruf beispielsweise Dinge wie Dateisystem, Rechte, Anzahl Unterverzeichnisse etc. angeben. Aber standardmäßig steht diese Einstellung dann auf "auto" oder "none"...
Und diese Erklärung genau dorthin über die Einstellung zu packen halte ich für sehr viel praktischer als irgendwo in einer Dokumentation (die sich sonstwo finden lässt) danach zu suchen.

[striderx]

Von der IT eines großen Konzerns kenne ich Programmiervorgaben, die einen bestimmten Anteil von Kommentierungen einfordern (z. B. 20 Prozent des Quellcodes).

Der Hintergrund dafür: Geschäftskritische Anwendungen müssen auch wartbar sein, nachdem die ursprünglichen Entwickler nicht mehr zur Berfügung stehen. Des weiterem wird in diesem Bereich ja auch tailoristisch gestückelt und/oder nach draußen Vergeben - da ist es unabdingbar, dass mit vertretbarem Aufwand nachvollziehen kann, was in dem jeweiligen Segment los ist. Und ich bezweifele, dass man bei komplexen Anwendungen Sourcecode immer so schreiben kann, dass er leicht nachvollziehbar ist.

Anders sieht es natürlich aus, wenn man Einzelkämpfer ist. Dann kann man sich auch mit Nachrichten an sich selbst begnügen (siehe Post von Frank).

Und noch ein Gedanke: Nach meiner Erfahrung kann die Formulierung eines Kommentars durchaus noch einmal eine Art der Qualitätssicherung sein.

[dummzeuch]

Mein Problem mit Kommentaren ist, dass sie nicht gepflegt werden. Da beschreibt der Kommentar etwas voellig anderes als der Code und man sucht sich dumm und daemlich. Lieber kein Kommentar als ein falscher. Mir waere es wesentlich lieber, wenn meine Kollegen beim Commit eine sinnvolle Beschreibung ihrer Aenderungen eingeben wurden.

Die generelle Regel bei Komentaren sollte sein: Beschreibe das Warum, nicht das Was, es sei denn, es ist offensichtlich. Ueberarbeite lieber nochmal den den Code, um ihn verstaendlicher zu machen (Tipp: Sprechende Prozedur- und Variablennamen) als einen Kommentar zu schreiben.

Inc(i); // Wichtig: i um eins erhoehen

[mm1256]

Zitat von Luckie:

Ich versuche es auch so, dass der Code von alleine erklärend ist. Eine Versionshistory im Header kann, aber denn noch sinnvoll sein, wenn man den Code weggibt. Die haben dann ja meistens nicht den Verlauf im Repository. Ändere ich bestehenden Code von anderen kommt meist ein:

Delphi-Quellcode:

// MP start
// [Datum, Grund]
...;
...;
...;
// MP ende

in den Code. Dann kann man auf den ersten Blick nachvollziehen wer, was, wo warum geändert hat ohne alte Versionen erst vergleichen zu müssen.

Genauso handhabe ich das generell nur meine Syntax ist etwas anders

Delphi-Quellcode:

...;
...; {!!.VERSION und alternativ das Datum}
...;

wobei VERSION die Versions-Nummer ist. Der praktische Vorteil kommt zum Tragen wenn man alle Änderungen einer bestimmten Version innerhalb eines Projektes im Suchfenster auflisten möchte, um dann schnell zu den Änderungen zu springen.

Übrigens, ich hab's nicht erfunden. Hab mir diese Praxis in den 90-er Jahren von TurboPower abgeguckt. Hat sich bis heute bestens bewährt

[Ghostwalker]

hmm...also...selbst mit rund 20 Jahren Erfahrung als Entwickler kann ich sagen, das ich bisher noch
kein wirklich optimales System gefunden habe.

Im moment arbeite ich so, das ich, im Quelltext selbst, soviel erkläre, wie notwendig, um zu verstehen was eine Methode macht. Komplexere Teile, die womöglich noch Zusammenhänge erklären sollen, werden nur mit einem Verweis gekennzeichnet, der in eine extra Doku läuft. Sachen, wie z.B. Versions-History oder Lizenz-Hinweise haben imho im Quelltext nix verloren, da sie keine Informationen zur Funktion des Quelltextes liefern. Auch sollten sinnlose Kommentare vermieden werden, wie z.B.:

Code:

   Procedure Foo();
   var
     i : integer;
   begin
     //i ist eine Schleifenvariable vom Typ integer
     for i := 1 to 10 do
     begin
        ...
     end;
   end;

(He...nicht lachen....sowas ist mir schon untegekommen)

[hoika]

Hallo,
also gerade wenn es eine Fremdfirma ist, finde ich eine Dokumentation im Quellcode sehr wichtig.
Also auch, was eine Methode macht, welche Parameter sie hat usw.
Das führt übrigens auch dazu, sich Gedanken bei der Entwicklung selbst zu machen,
schon allein, wenn man mit einem Satz schreiben soll, was sie macht.

Richtig ist, dass eine externe Dokumentation immer der Implementierung hinterherhinkt,
sobald die erste Änderung aufgetreten ist.

Sogar im eigenen Entwicklerkreis arbeitet doch mal jeder an einem anderen Code.
Ich neige dazu, bei kleineren Änderungen den alten Code auszuklammern und mit einzuchecken:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Warum?
Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.
Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Von Zeit zu Zeit gehe ich die Quellcodes durch und lösche den alten auskommentierten Code.

So habe ich alles, was ich will:
den alten und neuen Code für eine Weile nebeneinander
nach einer Weile nur noch den neuen Code
die Änderungen pro Revision über das CVS in dem Diff

[BUG]

Zitat von hoika:

Richtig ist, dass eine externe Dokumentation immer der Implementierung hinterherhinkt,
sobald die erste Änderung aufgetreten ist.

Stimmt, und ehrlich gesagt sind sind die Teile, die ich in externer Doku unterbringe, nie Sachen die man einfach mal so ändert .. sondern eher größere Konzepte und Zusammenhänge. Auch kompliziertere Beweise, Laufzeitabschätzungen oder Benchmarkergebnisse würde ich nicht in Code haben wollen (hab aber auch eher selten).

Zitat von hoika:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Gerade das Beispiel finde ich superunübersichtlich.

Zitat von hoika:

Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Nur falls du es noch nicht kennst: die meisten SCM haben irgend eine Variante von Blame. In manchen Fällen kann das helfen.

Zitat von hoika:

Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Git kann binäre Suche, aber dazu kann ich mich auch nie durchringen


Während des Arbeiten lass ich mir den alten Code auch gerne mal stehen (auch bei Zwischen-Commits), aber spätestens vor dem Merge mit dem Main-Branch fliegt dass alte Zeug weg.

[Ghostwalker]

Zitat:

Also auch, was eine Methode macht, welche Parameter sie hat usw.

Das sollte man eigentlich am Quelltext ablesen können (Stichwort sprechende Bezeichner). Viel wichtiger ist, den Gedankengang hinter der Implementierung kurz zu erläutern.

Zitat:

Code:

{ Entwickler-Kürzel, Datum, Version }
{ argz, was soll denn das -2 ??? }
//for i:= 0 to StringList.Count-2
for i:= 0 to StringList.Count-1
{ Ende: Kürzel, Datum Version }

Auch das ist, imho kein so gutes Beispiel, da die Gefahr besteht, das im laufe der Zeit so etwas daraus entsteht:

Code:

{ AM, 01.03.2010, 1.0 }
{ argz, was soll denn das -2 ??? }
{ BM, 05.03.2010, 1.1 }
( Überladene Version von Stringlist )
{ AM, 10.03.2010, 1.2 }
{ -2 führt aber zu einem Zugriffsfehler }
{ BM, 12.03.2010, 1.3 }
( Unit an der falschen Stelle )
for i:= 0 to StringList.Count-2
//for i:= 0 to StringList.Count-1
{ AM, 01.03.2010, 1.0 }
{ BM, 05.03.2010, 1.1 }
{ AM, 10.03.2010, 1.2 }
{ BM, 12.03.2010, 1.3 }

Das ist so ein Beispiel wo man vor lauter Kommentar, den Quelltext nicht mehr erkennt

Zitat:

Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Der "Schuldige" und das Datum nützen (aus meiner Erfahrung) nur selten etwas, insbesondere
wenn selbiger nicht mehr für die Firma tätig ist. Und selbst wenn er noch Verfügbar ist, wird
er dir auch nicht sagen können warum er das vor 2 Jahr so oder so gemacht hat.

Zitat:

Und der Debugger kann mir nicht sagen, wieso ein Code plötzlich funktioniert/nicht funktioniert,
indem er mir die Änderungen zur Vorversion anzeigt.

Das kann dir im Regelfall keiner sagen. Richtig gepflegt, zeigt dir die Vorversion an was anders gemacht wurde und bringt dich u.U. darauf, wo das Problem zu suchen ist.


Ob ein Kommentar sinnvoll und nützlich ist, ist von sehr vielen Faktoren abhängig. Ich denke eine generelle Lösung gibts da einfach nicht.

[Der schöne Günther]

Zitat von hoika:

Warum?
Weil ich bei 100 Änderungen an einer Datei mit jedem CVS ewig brauche,
um den Entwickler und das Datum zu erfinden, der eine bestimmte Änderung verbrochen hat.

Nur als Hinweis: Selbst für das RAD Studio gibt es z.B. die "Blame Bar" welche dir, egal ob SVN, Git oder HG, zu jeder Zeile sagen kann wer es verbrochen hat - Steht einfach links neben der Zeilennummer der Name. Fährt man mit der Maus drüber siehst du das Datum und den Checkin-Kommentar. Der beinhaltet ja die Motivation was diese Änderung im großen Kontext bewirken sollte.

Alte Bestandteile ausklammern im Code lassen - Niemals. Würde ich nur zulassen wenn es ein historischer Fehler ist der 10 Jahre lang ausgeliefert wurde und jetzt das bestehende Verhalten (zumindest im internen Ablauf) ändert.

Hoppla, der Hinweis mit Blame kam schon.