Wie und wieviel kommentiert Ihr Euren Code

[Sherlock]

Tja, selbsterklärender Code ist das hohe Ziel der Entwicklerschaft.

Allein, er ist es leider nur für ungefähr eine Woche. Darum gilt: Es gibt keinen selbsterklärenden Code. Jeder ist der Meinung super Code zu produzieren, der sogar in aller Regel tut was er soll. Nur wird dieser Code von Menschen mit unterschiedlichem Kenntnisstand sehr unterschiedlich wahrgenommen (vulgo: verstanden). Darum schreibe ich zumindest was der folgende Code tun soll. Das hilft beim schnellen Überfliegen ungemein, man muss nämlich nicht erst compilieren, sondern kann sich auf die Prosa verlassen. Und nein, ich schreibe keine Kommentare für

Delphi-Quellcode:

writeln('Hello World')

. ;)

Sherlock

[Delphi-Laie]

Ja, auch meine Wenigkeit ist in dieser Hinsicht eher ein ziemlicher, aber kein absoluter Faulpelz.

In dem Augenblick, in dem man den Code schreibt, ist einem der Grund dafür klar, das Kommentieren daher (erstmal) unnötig.

Man muß also zwei Hürden überwinden:

1. Man muß sich in diesem Augenblick (oder unmittelbar danach) bewußt werden, daß es ggf. mal wieder etwas zu kommentieren gibt.
2. Man muß entscheiden, ob und inwieweit der Code "selbsterklärend" ist - oder eben nicht. Das ist schwierig einzuschätzen, weil man selbst sein schlechtester Korrekturleser ist.

Oft wird diese Faulheit bestraft, indem man sich Tage bis Jahre später dann auch erst wieder mehr oder minder mühsam in seinen eigenen Code, zumindest Teile davon, meistens ziemlich mühsam hineindenken muß. Klar, man hat dabei einen Heimvorteil, der aber mit der Zeit schwindet.

[himitsu]

Bei API-Wrappern versuche ich mich grade an einer Dokumentation durch Attribute, wo z.B. DLL, wichtigste Exports und nötige Berechtigungen genannt werden.
Aktuell haben sie keinerlei Funktion, könnten aber in Zukunft ausgelesen werden.

ALLERDINGS geh ich da etwas vom Standard weg ... meine Attribute gelten auch für ALLES Nachfolgende, ab der Definition, innerhalb der Definitionsebene und nicht nur für die EINE Nachfolgende Methode/Typ.
=> nur das Nötigste und nicht alles mit Attributen vollgekleistert, sonst erkennt man den Code ja nicht mehr. :stupid: (ich hätte mir Postfix-Attribute gewünscht ... wie ein //-Kommentar, hinter die CodeZeile)

[Lemmy]

ich notiere mir die Verbindung zu externen Dokumenten wie Pflichtenheft / Anforderungskatalog, damit ich zum einen nachlesen kann warum der Code so ist wie er ist (hoffentlich) und zum anderen bei Änderungen an der Anforderung die relevanten Codestellen schnell finde.

Ansonsten dokumentiere ich dann, wenn ich denke, dass der folgende Code "unerwartet" ist - man könnte vermutlich auch sagen, dass solcher Code "riecht".

Als Ausnahme natürlich Interfaces wenn diese als Bibliothek auch anderen zur Verfügung gestellt werden, dann muss das per XMLDoc/Documentation Insight dokumentiert sein...

[SProske]

Ergänzend zu bisher genannten Punkten
- Berechnungsformeln (Herleitung, Leselinks etc.)
- Codeschnipsel die aus dem Web übernommen oder hergeleitet wurden
- Wenn ich irgendwo beim Debuggen ewig hing, versuche ich meine Erkentnisse zu dokumentieren (Refaktoring wäre natürlich besser, aber wann hat man shcon mal Zeit...)
- wenn Code für irgendwelche Sonderfälle angepasst werden musste -> Doku für diesen Sonderfall

[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 :cyclops:
Ohne hier jetzt irgendwie werten zu wollen, war mir das nicht bewusst, dass scheinbar viele Leute in diesem Aspekt nicht unterschieden.

[himitsu]

Jupp, Quellangaben von Fremdcodes, sind auch immer gut, wenn sie vor Ort dokumentiert sind. (nicht nur wegend der Lizenz, sondern auch für zukünftige Updates und Bugfixe)

[Sherlock]

Zitat:

Zitat von Nersgatt (Beitrag 1349707)

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 :cyclops:
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. :stupid:

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. :cyclops:

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

Delphi-Quellcode:

MWSF=11;

einen Mehrwertsteuerfaktor meint. Und wenn ein

Delphi-Quellcode:

GetCaseKey

heute noch sprechend ist, weil die Datenbank ein Feld CaseKey hat, dann ist das Morgen ein

Delphi-Quellcode:

GetCaseID

. Gut man könnte auch

Delphi-Quellcode:

GetCasePK

nutzen, aber was wenn es sich nicht um den PK handelt??

Gruß
K-H