Wie und wieviel kommentiert Ihr Euren Code

[Nersgatt]

Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.

[Sherlock]

Zitat von Nersgatt:

Wenn ich diesen Thread so lese, überkommt mich das Gefühl, dass für viele Leute "Kommentar" und "Dokumentation" das selbe zu sein scheint. Das finde ich interessant
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.

Die Grenzen verschwimmen, wenn man ein Tool verwendet, daß aus dem Code die Dokumentation erzeugen soll.

Sherlock

[Aviator]

In neuen Programmen versuche ich im Interface Abschnitt die Methoden mit Hilfe von XML Dokumentation zu beschreiben. Auch die Parameter. Nichts desto trotz verwende ich sprechende Parameternamen um nicht immer wieder nachlesen zu müssen. Aber auch damit andere eine Methode aufrufen bzw. begutachten können wenn ich den Code weitergeben müsste.

Bei alten Projekten versuche ich neue Methoden immer etwas zu beschreiben. Die stechen dann zwar oft heraus weil sonst nix anderes Dokumentiert ist, aber immerhin besser als nichts.

Kommentare verwende ich im Code ebenfalls wenn bestimmte Stellen sehr komplex sind und es einfach nicht besser/übersichtlicher zu programmieren ist.

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.

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

[jaenicke]

Zitat von 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.

Dafür sind solche Vorgaben oft genau nicht geeignet. Ich habe schon solche Projekte gesehen. Da wurde dann um die Quote zu erfüllen extra kommentiert, dass eine Schleife für jeden Eintrag einmal durchlaufen wird usw., dafür wurden Variablennamen oft nur mit einem Zeichen geschrieben. Denn die Erklärung steht ja im Kommentar.
Das macht den Quelltext dann deutlich schlechter lesbar und extrem schlecht zu warten.

Deshalb stammen solche Vorgaben oft aus dem Management und nicht von denjenigen, die damit arbeiten. Um es mal vorsichtig auszudrücken.

Viel wichtiger als Kommentare oder Dokumentationen der einzelnen Routinen ist erst einmal eine Gesamtdokumentation, in der drin steht wie das ganze Projekt organisiert ist, wie die Abläufe grundsätzlich sind (Pattern, Dateiorganisation, ...), usw.

Denn wenn der Quelltext sauber geschrieben wurde, lese ich den Code eher schneller als jede Dokumentation. Wenn ich aber keinen Grundfahrplan habe wie das Projekt aufgebaut ist, finde ich mich erst einmal schlecht in das Projekt hinein. Und das kostet dann wirklich sehr viel Zeit.

Zitat von himitsu:

Die guteren CVS sagen dir aber wer welche Zeile zuletzt eingecheckt hat.
Bei SVN nennt sich das Blame (Schuld).

Und man kann dann auch von dort aus die vorherige Änderung der Zeile suchen usw., egal ob bei Git, Mercurial, SVN, ...

[hoika]

Hallo,
ich hatte ja gesagt, dass die auskommentierten Änderungen auch mal gelöscht werden.
Das mit dem Blame habe ich so nicht verstanden ...
Wir haben SVN, mal im RedBook lesen.

Trotzdem möchte ich durch Lesen des Quellcodes sofort wissen, wann wer für welche Version das eingebaut hat.
Und Version muss nicht mit der SVN-Branch ocer SVN-Tag übereinstimmen.

Aber das soll jeder ja so machen, wie er es gewohnt, versteht oder es gefordert wird.

http://svnbook.red-bean.com/de/1.7/s...n.c.blame.html
Nun ja, so gut ist das dann doch nicht (Stichwort Leerzeichen korrigiert).
Aber für sowas haben wir ja eh keine Zeit

[p80286]

Wenn alles so läuft wie gedacht, bracht man keine Kommentare.
(Und die Erde ist eine Scheibe)

Bei der Durchsicht von alten Code-Friedhöfen ist mir aufgefallen wieviel Kontext für das Verständnis notwendig ist, und der fehlt nach ein paar Jahren. Es ist nicht selbstverständlich, daß MWSF=11; einen Mehrwertsteuerfaktor meint. Und wenn ein GetCaseKey heute noch sprechend ist, weil die Datenbank ein Feld CaseKey hat, dann ist das Morgen ein GetCaseID . Gut man könnte auch GetCasePK nutzen, aber was wenn es sich nicht um den PK handelt??

Gruß
K-H

[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