Wie und wieviel kommentiert Ihr Euren Code

[v2afrank]

Hallo,
wir haben ein Projekt an ein externes Softwareunternehmen vergeben und ich habe jetzt von denen den ersten Code bekommen.
Was mir aufgefallen ist, ist die Menge an Kommentaren, die fast gleich 0 ist. Laut Clean Code sollte das ja wohl auch der empfohlene Weg sein. Wir haben hier bei uns in der Firma selber Regeln aufgelegt wie Unitköpfe und Funktionen dokumentiert und kommentiert werden sollen. Jetzt interessiert mich einfach mal wie Ihr das so handhabt. Haltet Ihr Euch eher an das CleanCode Prinzip oder ???

[Valle]

Ich kommentiere relativ wenig. Methoden, deren Zweck nicht unmittelbar ersichtlich ist, werden im Code dokumentiert. Codestellen, die unerwartetes oder unverständliches tun auch. Ansonsten versuche ich den Code so zu schreiben dass er sprechend ist und nicht kommentiert werden muss.

[haentschman]

Moin...:P

[meine Meinung]
Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig. :zwinker: Wenn man ein Versionskontrolsystem hat ist das doppelte Arbeit. Desweiteren sind sprechende Procedurnamen / Parameternamen das A + O. Da erübrigt sich meistens ein Kommentar. Persönlich sortiere ich meine Proceduren nach dem Typ... (...Eventhandler, Work, GUI Events, Actions etc.) :zwinker: Andere Suchen mit den Hilfsmitteln über den QT. Ich mag einfach keine Unordnung... :P
Wichtig allerdings ist das Kommentieren von Prozeduren bezüglich der Funktionsweise von Blöcken / einzelnen Zeilen z.B. wenn es notwendig erscheint.

...Also ich kommentiere dann nur wenn notwendig. :zwinker:
[/meine Meinung]

@Valle: +1

[himitsu]

Da alle meine Codes selbsterklärend und leicht verständlich sind, hab ich natürlich keinelei Kommentare im Code.



Spaß bei Seite.
Ich führe meine Dokumentation im Code, also sind mindestens an vielen Funktionen/Typen/Konstanten (im Interface) entsprechende PasDoc XMLDoc (Documentation Insight) und ich führe das aktuell auch für UnitHeader ein.

Im Code wird vorallem "schlecht" Erkennbares, sowie "komisches" und abweichendes Verhalten kommentiert, sowie "böse" Codeoptimierungen, wo ich den OriginalCode dahinter schreib, damit man versteht was gemacht wird.

Zitat:

Ich halte die Kommentare bezüglich der History (Unitkopf, Procedurekopf) für überflüssig

Historie mach ich auch nicht.

Bei Komponenten-Units steht im Kopf das zugehörige Projekt, sowie die Copyright/Lizenz (nur der Name und das Detailierte als Link)

Bei Prozeduren mach ich auch nicht mehr überall die Dokumentation dran (hatte ich mal angefangen, aber lass ich grade wieder von ab) ... Jupp, sprechende Bezeichner sind immer besser, aber machmal muß man einfach bissl was erklären.

[Der schöne Günther]

Ich habe nichts neues beizutragen, nur eine Frage in der Richtung:

Ich habe nie verstanden was es bringt eine Unit selbst zu kommentieren. Angenommen sie enthält entweder

1. Eine Klasse
2. Ein Interface und ein dazugehöriger Exception-Typ
3. Einen Haufen Nummern-Konstanten

Was sollte der Text in den ersten Zeilen der Unit einem erzählen können was man nicht auf den ersten Blick sieht?

[Nersgatt]

Ich mach es wie Valle. Mein Code ist wenig bis gar nicht Kommentiert. Nur, wenn es wirklich schwer zu durchschauende Stellen sind. Und die versuche ich soweit es geht zu vermeiden. In diese Vermeidung investiere ich durchaus auch einige Zeit.

Wenn die Fremdfirma die Funktionsköpfe etc. nach euren Regeln kommentieren soll, dann müsste das entsprechend im Vertrag geregelt werden.

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

...:cat:...

[Mavarik]

Kommentare nur wenn der Code nicht auf den 1. Blick zeigt was Sache ist.

oder auch gerne mal Kommentare wie:

// Frank lass hier die Finger weg, Du hast schon 3x versucht das zu optimieren - es bringt nix...

Mavarik

[Mavarik]

Zitat:

Zitat von sakura (Beitrag 1349686)

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.