Quellcode Kommentieren

[bernau]

Zitat von sx2008:

Die Nachteile der Zwangskommentare sind:
* Zeitverschwendung durch Einfügen und Pflegen von Kommentaren die keinen Zusatznutzen bringen
* visuelles Störfeuer - je mehr Zeichen auf dem Bildschirm sind umso mehr Kapazität benötigt das menschliche Gehirn um Wichtiges von Unwichtigem zu trennen
* die Stellen die wirklich mal einen Kommentar haben fallen gar nicht auf weil überall Kommentare stehen
* anstatt darüber nachzudenken wie man die Funktionen sprechender machen könnte verlässt man sich auf nutzlose Kommentare die im Zweifelsfall doch eh falsch sind weil sich Funktionsname und/oder Parameter geändert haben

Visuelles Störfeuer: Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.
Eine Schnelle Info, wann diese Procedure angelegt wurde finde ich auch sehr gut. Benutze zwar ein Versionscontrolsystem. Aber das würde unnötige klicks benötigen.
Kommentare stehen im Procedure-Header nur, wenn es tatsächlich etwas wichtiges zu beachten gibt.

[Dejan Vu]

Zitat von bernau:

Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.

Da reicht dann aber ein '(****** ... ****)' o.ä. Wenn's denn sein muss (ich finds grauslig).

Wenn man eine Methode kommentieren muss, ist sie zu lang, hat einen falschen Namen oder beides. Nur wenn ich z.B. eine Gesetzesvorlage (oder eine Spec) explizit umsetze, oder eine mathematische Formel/Verfahren etwas komplexeren Ausmaßes, kommt ein kurzer Kommentar rein mit Quelle.

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine. sx2008 hat das meiste ja schon erklärt.

[p80286]

Kommentar immer da wo's notwendig ist. Z.B. Uppercase,Upcase,Ansiuppercase... sollten mit einem Kommentar versehen werden, damit man die Feinheiten nicht immer nachschlagen muß.

Gruß
K-H

[Sherlock]

Zitat von Dejan Vu:

Zitat von bernau:

Ich finde es sehr angenehm, wenn zwischen Proceduren ein "erkennbarer Block" steht, der zwei Proceduren voneinander trennt.

Da reicht dann aber ein '(****** ... ****)' o.ä. Wenn's denn sein muss (ich finds grauslig).

Wenn man eine Methode kommentieren muss, ist sie zu lang, hat einen falschen Namen oder beides. Nur wenn ich z.B. eine Gesetzesvorlage (oder eine Spec) explizit umsetze, oder eine mathematische Formel/Verfahren etwas komplexeren Ausmaßes, kommt ein kurzer Kommentar rein mit Quelle.

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine. sx2008 hat das meiste ja schon erklärt.

Das ist ein sehr weit verbreiteter und sehr alter Irrtum, der einfach zu wiederlegen ist.
Du gehst davon aus, Dein Code sei korrekt und lesbar, und bedürfe darum keines Kommentars. Das sind schon zwei sehr persönliche Ansichten, die meiner Meinung nach nichts bei der Entwicklung zu suchen haben. Wen Kommentare stören, der kann sie gerne wegfalten. Aber in den Code gehören nunmal zumindest Kommentare, die erklären, was zum Teufel der Schöpfer eigentlich mit folgender Methode vor hatte - mindestens. Und wenn der Methodenname einen ganzen Satz ergibt - was nun wirklich nicht der Realität entspicht. Dennoch gehört da ein Kommentar davor, der darlegt, was man da warum tun wollte. Ich habe das gerade erst letzte Woche erlebt, daß ein simpler Zweizeiler überhaupt nicht tat, was man an der Stelle erwartet hätte. Er war schlicht falsch. Wunderschön in sich, ja, denn kein störender Kommentar weit und breit, und die Methode hatte einen ganz toll sprechenden Namen. Aber was da passierte, entsprach so gar keiner Spezifikation und führte im folgenden zu massiven Problemen. Darum: Lieber zu viel Kommentare als zu wenig. Und bitte die Kommentare aktuell halten. Dann ist ja schon die halbe Doku fertig.

Sherlock

[Dejan Vu]

Zitat von Sherlock:

Du gehst davon aus, Dein Code sei korrekt und lesbar, und bedürfe darum keines Kommentars.

Nein. *Wir* gehen davon aus, das Team. Man muss schon professionell vorgehen, damit 'guter' Code auch gut ist. Und dazu gehört, das man die Scheuklappen abnimmt und den Code im Team reviewt. Ich mecker auch am Code meiner Kollegen rum, wenn die das nicht KISS-technisch und für mich verständlich umgesetzt haben.

Zitat:

Aber in den Code gehören nunmal zumindest Kommentare, die erklären, was zum Teufel der Schöpfer eigentlich mit folgender Methode vor hatte - mindestens.

Wieso? Sie ist doch selbsterklärend. Ich kommentiere doch nicht das offensichtliche. Das *ist* doch gerade die Krankheit.

Zitat:

Und wenn der Methodenname einen ganzen Satz ergibt - was nun wirklich nicht der Realität entspicht.

Dann ist die Methode zu komplex, gehört refaktorisiert und dann passt das auch mit dem Namen.

NIE NIE NIEMALS versuchen, mit Kommentaren den Code einer Methode zu erklären. Entweder ein geschulter Programmierer (kein Newbie, is klar) kann das lesen, oder ich muss mich ransetzen und das lesbar machen. Entweder durch Refaktorisierung oder eben (wer versteht schon die Syderberg-Shnayderman-Transformation im Rotationsgefubbel der 7.Querdimension?) durch einen knappen Kommentar mit Quelle. So halten wir das. Und wir sind alles alte Säcke mit 10-30 Jahren VerzweiflungProgrammiererfahrung.

Wir kommentieren allerdings auch Workarounds um VCL-Bugs, ist klar.

Zitat:

Darum: Lieber zu viel Kommentare als zu wenig. Und bitte die Kommentare aktuell halten. Dann ist ja schon die halbe Doku fertig.

Also 'zuviel' ist genauso falsch wie 'zu wenig'. Gerade richtig ist die Devise. Wenn deine beiden Codezeilen auch durch Refactoring nicht lesbarer werden (ich bezweifle das, aber z.B. bei komischen Formeln ist das so), dann wird erklärt, was das ist. Ansonsten kann ich dir jeden Code so umformulieren, das er verständlich wird (sofern Du programmieren kannst, bei meiner Frau klappt das nicht).

Und 'aktuell' ist die Doku eben per se nicht. Geht nicht, nirgens (außer bei Dir zu hause vielleicht). Weil Zeitdruck. Abgabe. Termin. Feierabend. Nächster Task oder Ticket. Anruf vom Teamleiter. Meeting. Frage vom Newbie oder Oldie. Usw. Wieviel Zeit da ins Land schreitet, die ganzen blödsinnigen, redundanten Kommentare nachzupflegen...Es ist Zeitverschwendung. Sagen zumindest die, mit denen ich bisher zusammengearbeitet habe.

Ich dokumentiere meinen Code jedenfalls nicht, sondern schreibe selbsterklärenden Code. Das ist die beste Kommentierung. Klar, das es auch Blödsinn gibt:

Delphi-Quellcode:

function GibMirDieMehrwertsteuer (einBetrag : TGeld) : TGeld;
Begin
  result := einBetrag * Einkommensteuersatz;
End;

Aber immerhin beinahe instantan ersichtlich, das der Programmierer einen schlechten Tag hatte.

Einzige Ausnahme unserer Regel (Redundanten Kommentar vermeiden): Die API. Auch wenn die Methode heißt 'ConvertRawBytesToHexString', muss eben darüber stehen: 'Converts raw bytes to a hex string'. Und dann klappts auch mit der Doku (weil die dann nämlich leer wäre und da fragt man sich auch? Wieso ist die Doku an dieser Stelle leer? Diese Schlampen!)

Delphi-Quellcode:

// Converts raw bytes to a hex String
// Parameter: inBytes - an Array of bytes to convert
//    returns the hex string
function TFoobar.ConvertRawBytesToHexString(inBytes : TByteArray)

Der redundantischste Kommentar der Welt (getoppt nur durch  inc(i); // increase i ), aber (weil API Funktion) notwendig. Sonst nicht. Bei C# bekomme ich dadurch auch gleich meinen Live-Kommentar, wenn ich die Code-Completion anwerfe.


Da es Glaubenssache ist, einigen wir uns darauf, das Du Recht hast und ich auch und jeder sein Zeugs so macht, wie er es für richtig findet. Aber ich hoffe, wir sind uns darin einig, das selbsterklärender Code besser ist als ein Kommentar, der versucht, die durch Meth gestörten Gehirnwindungen des Programmierers zu erklären.

[mjustin]

Zitat von Dejan Vu:

Kommentare sind böse und lügen. Einfach mal 'Clean Code' lesen, dann weiß man, was ich meine.

Clean Code (bzw. Robert C Martin) sagt ja nicht, dass alle Kommentare schlecht sind, er nennt auch einige Fälle 'Guter' Kommentare. Auch ich würde keine API / Bibliothek / Komponente schreiben, in der "High-Level" Kommentare zu den öffentlichen Klassen und Methoden fehlen.

[Dejan Vu]

Das war sehr plakativ von mir. Ausnahmen (wie erwähnt) bestätigen die Regel.

[himitsu]

Zitat von Dejan Vu:

Und 'aktuell' ist die Doku eben per se nicht. Geht nicht, nirgens ...

Drum dokumentiere ich auch meinen Code aufgrund der Tatsache, daß der Code die Dokumentierung ist, werden dort eben auch die Interfaces sortiert/gruppiert.

Bei der Implementation hab ich die Sortierung ja aufgegeben, außer da, wo mehrere Funktionen versionsabhängig via Compilerschalter deaktiviert werden, welche dort in einem {$IF} landen, bzw. bei einem älteren größeren Projekt, wo ich die Implementation, der Übersicht wegen, in mehreren Regionen zusammengefasst hatte.


Aber ja, zuviele und vorallem "nutzlose" oder gar verwirrende Kommentare machen nichts besser ... eher das Gegenteil.


Und ich würde versuchen alle Funktionsbeschreibungen ins DocInsight zu legen, welches sich relativ problemlos um neue Felder erweitern lässt, damit man diese Kommentare auch in eine externe Dokumentation übernehmen kann, und vorallm damit sie im HelpInsight verfügbar sind.

[Sherlock]

Zitat von Dejan Vu:

Da es Glaubenssache ist, einigen wir uns darauf, das Du Recht hast und ich auch und jeder sein Zeugs so macht, wie er es für richtig findet. Aber ich hoffe, wir sind uns darin einig, das selbsterklärender Code besser ist als ein Kommentar, der versucht, die durch Meth gestörten Gehirnwindungen des Programmierers zu erklären.

Akzeptiert

Das mit dem Meth muss ich mal bei Gelegenheit ausprobieren (lassen).

Was die aktualität der Doku angeht: Wir müssen unter anderem gemäß ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Sherlock

[Dejan Vu]

Zitat von Sherlock:

Das mit dem Meth muss ich mal bei Gelegenheit ausprobieren (lassen).

Drogen und Programmieren passt irgendwie nicht. Entweder es wird viel zu kreativ und bunt, komplett verworren oder absolut krank. Hmm.

Zitat:

ISO 13485 entwickeln, da gibt es kein SW-Release ohne Doku.

Das betrifft doch nur die Doku und keine Quellcode-Kommentare, oder irre ich mich?