Wie und wieviel kommentiert Ihr Euren Code

[sakura]

Ich kann nicht verstehen, wenn jemand nicht oder nur wenig kommentiert.

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.

Gerade wenn mehrere an einem Projekt arbeiten ist dieses unabdingbar. Natürlich kann man vieles leicht erkennen, wenn man sich den Quelltext anschaut, aber das kostet immer wieder Zeit, jedes Mal. Die Methoden kurz zu dokumentieren kostet nur einmal Zeit

Innerhalb von Methoden eignet es sich vor dem Erstellen des eigentlichen Codes in PDL (programm description language) kurz die gewünschte Logik zu schreiben und dann den Code zu schreiben. Das erleichtert das spätere Korrigieren von Fehlern in Logik und Implementierung ungemein.

Alles andere erachte ich inzwischen als wahrlich schlechten Stil, und davon habe ich genug hier vor mir

Insgesamt sollte die Dokumentation von Codes nicht im Wege stehen, sondern helfen. Insbesondere, wenn jemand anders mal am Code arbeiten muss. Selbst hundert leichte Methoden in einer Unit sind nur schwer zu verstehen, wenn man gar keine Marschrichtung kennt...

......

[Mavarik]

Zitat von sakura:

Wie oben schon angemerkt, für zumindest protected und public/published Members und alles im Interface-Bereich, sollte man immer dokumentieren, damit die Nutzer dieser Schnittstellen in der Doku das gewünschte Verhalten sofort verstehen können. Dafür eignet sich natürlich XMLDoc-Styles.

Was ein Interface macht sollte man erkennen. Wichtiger finde ich es, welche möglichen Exceptions auftreten können.

[JasonDX]

Ich versuche mich prinzipiell daran zu orientieren:
Der Code erklärt selbst, was er macht. Kommentare ergänzen das Warum wenn erforderlich.

Im Bezug auf Dokumentation von Methoden und Klassen: Klassen haben bei mir seltenst Dokumentation; Methoden dokumentiere ich dann, wenn sie außerhalb der Klasse sichtbar sind. Dabei konzentriere ich mich auf Grenzfälle, Exceptions und nicht zwingend intuitive Verhaltensweisen.

[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 writeln('Hello World') .

Sherlock

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

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

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