Wie und wieviel kommentiert Ihr Euren Code

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