Quellcode Kommentieren

**bernau**

Interessante Diskussion.
Vor allem, weil die meisten wohl nicht die Probleme haben, die Chemiker angesprochen hat. Wenn man nicht mehr im Thema drin ist oder wenn einem die Entwicklungsoberfläche fehlt (ganz zu schweigen von einem Versionskontrollsystem), dann ist Kommentar im Sourcecode doch sehr hilfreich.

Das bringt es auf den Punkt.

**mjustin**

Zitat von vagtler:

Zitat von mjustin:

[...] Ich kenne kein Versionskontrollsystem oder eine CSV-IDE Integration sie so etwas kann oder nur in die Nähe käme. [...]

Sowas möchte ich auch auf keinen Fall im Code haben. Das gehört in das Issue-Management und wird durch Branching und zu den Issues zugeordneten Commits gemanaged.

Die Sachbearbeiter im Issue- und Projekt-Management würden sich bedanken, wenn sie so etwas im Code nachschlagen müssten. Vom Accounting gar nicht erst zu reden... :p

Nein, der Code soll natürlich nicht mit Versionsinformationen auf Prozedurebene zugemüllt werden. Nur für die Nachverfolgung von Änderungen wäre es eine feine Sache, wenn man das Changelog auf eine Prozedur anstatt auf eine Datei beschränken könnte. Und ich kenne kein Tool, das das kann. Und wenn, dann wäre dessen Integration ähnlich dem hier bereits genannten "LiveBlame" sicher sehr hilfreich.

Das Issue- und Projektmanagement darf aufatmen, JIRA soll nicht abgeschafft werden

Zitat von p80286:

bei einem

markieren

Code:

if boolean(shl(shr(wert,1),1) then

wäre ich mir da nicht so sicher.

Refactoring:

markieren

Delphi-Quellcode:

			function SecondBitIsSet(aValue : Integer) : boolean;

Begin

  result := boolean(shl(shr(aValue,1),1)

End;

...

// statt kryptisch

if boolean(shl(shr(wert,1),1) then

// nun verständlich

if SecondBitIsSet(Wert) then ...

Zum Changelog: Einfach pro Task einchecken. Es gehört Disziplin dazu, aber das lernt man. Spätestens wenn man schon wieder eine Teamrunde spendieren muss, weil man zu schlampig war (Ich weiß, wovon ich rede). Ich brauche kein Changelog pro Prozedur. Ich brauche ein Changelog für die Change Requests und Bugfixes. Das Diff und 'Blame' zeigt mir dann, wer was wann wo geändert hat. Braucht man eigentlich nur beim Review.

**p80286**

Zitat von Dejan Vu:

function SecondBitIsSet(aValue : Integer) : boolean;

Leider hast du die Intention nicht getroffen. Wert sollte ein Word sein, gemeint war if wert>3 then , was ich aber auch erst einige Dutzend Zeilen später bemerkt habe.
Das ist mir in einem uralten TP-Programm über den Weg gelaufen. Leider konnte ich den Programmierer nicht mehr fragen warum er es so gelöst hat. Kommentar wäre da recht hilfreich gewesen.

Gruß
K-H

Zitat von p80286:

Leider hast du die Intention nicht getroffen.

Wieso 'Leider'? Mir doch wurst, war ja auch nur ein Beispiel.

Und wenn man sowas sieht, dann refaktorisiert man trotzdem. Wenn Du weißt, das das '>3' heißen soll, dann änderst Du das eben in '>3' oder schreibst ne Funktion 'HigherThanThree', was hier ein wenig dämlich wäre, aber den Kontext der Diskussion träfe.

Auf keinen Fall schreibt man als Kommentar dahinter: 'soll >3 bedeuten'. Wenn ich das sehe, zeige ich diesen Schnipsel im nächsten Meeting und frage, wieso der, der den Kommentar geschrieben hat, den Code nicht gleich refaktorisiert hat.....

PS: Ich hätte das durch einen Unit-Test abgesichert und da wäre mir dann schon aufgefallen, das da was nicht stimmen kann und den Namen angepasst...

**Headbucket**

Ich möchte auch mal meinen Senf dazugeben.

Ich habe vor 1 Jahr bei meiner jetzigen Firma begonnen und habe hier auch das Programmieren gelernt. Ich musste verschiedene Dinge an einem großen Projekt (mehr als 650000 Zeilen Code) erweitern.
Hier war ich auch extrem froh, dass ich oft gute Kommentare gefunden habe, die mir etliche Fragen erspart haben. Da die Units teilweise bereits 2000 erstellt wurde und die entsprechenden Leute nicht mehr in der Firma sind, hätte ich sowieso niemanden fragen können.

Ich stimme natürlich dem bisher gesagtem zu: Sinnlose Kommentare können wegbleiben und wenn es irgendwie geht, soll man die Funktion so benennen, dass sie logisch klingt.

Ich hatte aber z.B. oft mit sehr komplexen mathematischen Funktionen zu tun. Hier hätte ich mich ohne das Kommentar erstmal lange in die Materie einlesen müssen. So haben mir die Kommentare genau gesagt, welche Parameter ich übergeben muss. Die Parameter hatten natürlich auch aussagekräftige Namen, die mir aber als unwissender nicht weitergeholfen haben.

Sicherlich lässt sich alles auch nach Dejan Vu's Vorstellungen lösen, die ich teilweise echt gut finde. Man kann aber auch eine Zeile Kommentar schreiben anstatt eine Prozedur auf 5 aufzusplitten. Das ist dann wohl Geschmackssache.

Wer aber Zeit hat andere Leute wegen ihrer Kommentare in einem Meeting zu befragen...so viel Zeit möchte ich auch mal haben

Wir haben diese Zeit in unserer Firma (sehr kleines Entwicklerteam) nicht. Da hat niemand die Zeit jemand anderen seinen Code zu erklären bzw. durchzulesen. Wenn man dann doch mal Code eines anderen Programmierers verwendet, ist man über Kommentare sehr dankbar.

Gruß

Zitat von Headbucket:

Sicherlich lässt sich alles auch nach Dejan Vu's Vorstellungen lösen, die ich teilweise echt gut finde. Man kann aber auch eine Zeile Kommentar schreiben anstatt eine Prozedur auf 5 aufzusplitten. Das ist dann wohl Geschmackssache.

Richtig, aber der Kommentar wird bei Änderungen nicht(immer) mitgepflegt. Irgendwann hat der Kommentar nichts mehr mit dem Code zu tun. Dann lieber gleich aufsplitten. Bei Berechnungen ist das aber blödsinnig, außer, wenn Zwischenergebnisse irgendetwas Erhellendes ergeben oder für Prüfungen notwendig sind. Bei diesen Berechnungen verwendet man gerne kurze Bezeichner, wie a, alpha, m oder n. Das sind zwar aus codeästhetischer Sicht 'ganz schlimme' Bezeichner, aber jeder Mathematiker würde dir einen Vogel zeigen, wenn Du dann 'Fläche', 'Winkel', 'Matrixzeilenanzahl' und 'Matrixspaltenanzahl' schreiben würdest. Das ist im mathematischen Kontext usus, diese besonderen kurzen Bezeichner zu verwenden. Wichtig ist, das man das kapiert. Als Programmierer stoß ich mich ja auch nicht an 'i' und 'j' für Zähler: Also, alles immer im Rahmen.

Zitat:

Wer aber Zeit hat andere Leute wegen ihrer Kommentare in einem Meeting zu befragen

Nein, nein. Beim wöchentlichen Meeting werden von mir Best Practices, Patterns oder Knallkorken gezeigt und erklärt. Und wenn jemand zu faul war, Code zu verbessern, dann zeig ich das auch und erinnere an die Pfadfindertugend: "Hinterlasse den Code immer etwas sauberer, als Du ihn vorgefunden hast". Namen werden nie genannt, außer, jemand hat was Tolles gemacht, dann kriegt er ein Bienchen

. Bei Stilblüten lachen wir uns alle mehr oder minder schlapp, nur einer bekommt einen roten Kopf und lacht vielleicht etwas gekünstelt. Aber es ist egal, wer das war.

**Namenloser**

Zitat von Dejan Vu:

Zitat von Headbucket:

Sicherlich lässt sich alles auch nach Dejan Vu's Vorstellungen lösen, die ich teilweise echt gut finde. Man kann aber auch eine Zeile Kommentar schreiben anstatt eine Prozedur auf 5 aufzusplitten. Das ist dann wohl Geschmackssache.

Richtig, aber der Kommentar wird bei Änderungen nicht(immer) mitgepflegt.

Beim Funktionsnamen gibt es allerdings auch kein Naturgesetz, dass der automatisch mitgepfegt wird.

Zitat von Namenloser:

Beim Funktionsnamen gibt es allerdings auch kein Naturgesetz, dass der automatisch mitgepfegt wird.

Natürlich nicht. Wenn ich jedoch den Namen anpasse, sind automatisch alle selbstdokumentierenden Codestellen, die diese Methode verwenden, mit geändert. Und damit auch deren Dokumentation.

**Sherlock**

Dann jetzt mal Spaß beiseite: Bist Du hauptberuflicher Codereviewer? Weil das Zeitargument ist für mich äusserst nachvollziehbar. Freilich wird die jetzt gesparte Zeit später doppelt bis dreifach beim Bugfixing bezahlt, aber der Projektdruck ist nunmal jetzt und nicht in drei Monaten.

Sherlock