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.