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.

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

[Jim Carrey]

Zitat:

{ 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 }

Was ist denn, wenn Entwickler 2 innerhalb der Schleife etwas abändert?
Er darf dann ja nicht als Entwickler der kompletten Schleife angegeben werden.

Das würde zu einer großen Unübersichtlichkeit führen meiner Meinung nach.

[Sailor]

Knuth hatte da mal in den 90igern was, nannte sich "Literate Programming" mit Hilfe von WEB. Die Idee war, einen Text zu schreiben, aus dem durch Übersetzung sowohl der Programmtext als auch die Dokumentation erzeugt wurden. Ich habe das mal versucht, aber dann entnervt aufgegeben. Allerdings könnte das heute mit modernen Editoren, Displays und schnellen Rechnern anders aussehen. Müßte man sich mal wieder ansehen.

[p80286]

Zitat von Jim Carrey:

Delphi-Quellcode:

{ 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 }

Was ist denn, wenn Entwickler 2 innerhalb der Schleife etwas abändert?
Er darf dann ja nicht als Entwickler der kompletten Schleife angegeben werden.

Das würde zu einer großen Unübersichtlichkeit führen meiner Meinung nach.

Im Prinzip halte ich das für sehr gut, nur die Umsetzung ist nicht so dolle.

Delphi-Quellcode:

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

Ist meiner Meinung nach ausreichend. GGF. kann man auch die Vereinbarung treffen, das ersetzte Code Teile mit (* *) auskommentiert werden.

Gruß
K-H