Richtlinien für Kommentare

Hallo,

Ein bei mir immer wieder auftretendes Problem sind Kommentare und unterschiedliche Ansichten wie zu kommentieren ist und auch die Frage wie kommentiere ich so das ich mich nach einem Jahr Entwicklungspause in einem Programm schnell wieder zurecht finde. Ein paar Zeilen XML Doku über jeder öffentlicher Funktion und Property reichen nach meiner Erfahrung längst nicht aus.
Wie kommentiere ich innerhalb von Funktionen, blockweise oder garnicht ?
Kommentiere ich rein private Klassenvariablen?
Gibt es da Richtlinien oder Tools ähnlich FxCop oder Literatur?

Ich freu mich über jeden Tip !

Seitdem ich das Buch CleanCode gelesen habe, kommentiere ich (fast) gar nicht mehr 😃

Viel wichtiger als Kommentare sind selbsterklärende Variablen- und Funktionsnamen.

Zum Beispiel nicht so:
DelayTime = 10; // Sekunden

Sondern so:
DelayTimeInSeconds = 10;

Kommentare sollten außerdem nicht beschreiben was man tut, sondern nur warum man etwas tut. So reduziert sich die Anzahl der Kommentare auf das wesentliche.

Ja da war doch diese Geschichte von R. Westphal. Das mir aber ehrlich gesagt zu affig. 🤔

Natürlich ist der Code primär dafür verantwortlich verständlich zu sein
aber darum gehts mir garnicht, aber einer gewissen Grösse und Komplexität
gehts ohne einfach nicht, nach meiner Erfahrung. Der Code so sauber er auch sein
mag ist jeweils immer nur ein kleiner Schnipsel auf dem Bildschirm von was grösserem. Ich denke das entsprechende Class Diagramme und was man da in VS noch so anlegen kann vermutlich sehr dabei helfen (fällt mir gerade erst ein das es da noch was gibt) Mir gehts speziell darum Entwicklungspausen von Programmen zu handlen, sowohl von grossen als auch von kleinen Programmen, ich bin sicher das kennen viele Entwickler.

Je kleiner und abgeschlossener man die einzelnen Klassen hält, desto einfacher wird das kommentieren (und meist ist auch der Code dann besser).
Xml-Kommentare gehören für mich über jede Funktion (selbst die privaten, denn auch wenn der Inhalt noch so einfach ist, sagt ein Kommentar schneller und verständlicher aus was sie macht...verständlicher als der beste Funktionsname).
Kommentare innerhalb von Funktionen verwende ich selten. Wenn ich dazu neige welche zu verwenden fällt mir immer auf, dass man den Teil, den man kommentieren will, eigentlich besser in eine andere Funktion auslagern sollte (sozusagen dass ich gerade dabei war Kommentare zu nutzen, um längere Codeblöcke innerhalb einer Funktion zu trennen, was designtechnisch nicht so dolle ist).
Gibt es natürlich noch das "warum" mache ich jetzt grad dies und das.
Naja, hab ich hier und da drin, aber so etwas gehört meiner Meinung nach eher in ne Doku (kommentiertes Activity-Diagramm oder ähnliches..allgemein eignen sich bei größeren Projekten UML-Diagramme ganz gut als Erinnerungshilfe) als in den Code.
Von Tools halte ich nur bedingt was, erstens sind die meisten kostenpflichtig, zweitens sind sie überflüssig wenn man den Code selbst gut strukturiert hat, und drittens zeigen die einem den Code zwar ordentlich an, legen ihn aber nicht unbedingt ordentlich an (ich hatte da jedenfalls mal ein Tool, das hat kreuz und quer die Funktionen und Properties verteilt und hier kommentiert und da kommentiert, mit dem VS war es ein Graus das ganze wieder zu ordnen...weiß aber nicht mehr was das für ein Tool war).
Ob es speziell zu diesem Thema Literatur gibt weiß ich nicht.

gruß
sth_Weird

Ganz wichtig ist: Es gibt keinen selbstdokumentierenden/selbstkommentierenden Code! Kommentare sollten überall da geschrieben werden, wo es nicht eindeutig ist was, oder warum man etwas tut. XML-Doku über den Methoden ist sowieso selbstverständlich, um nachher ne gute Doc zu bekommen.

Wie kommentiere ich innerhalb von Funktionen, blockweise oder garnicht ?
Kommentiere ich rein private Klassenvariablen?

Methoden sollten möglichst so kompakt sein, dass sie keine Kommentare benötigen - lieber eine große Methode in mehrere kleinere aufteilen!
Ein Problem ist auch die Aktualität der Kommentare - veraltete Kommentare sind schlimmer als gar keine.

Und generell gilt: Qualität vor Quantität!

Hallo Sebastian.Lange,

... und unterschiedliche Ansichten wie zu kommentieren ist ...

eben wegen dieser unterschiedlichen Ansichten, wirst du hier sowieso keine eindeutige Antwort auf die Frage bekommen ... und da du die unterschiedlichen Ansichten ja wohl schon kennst, verstehe ich nicht so recht, was du dir überhaupt von diesem Thread versprichst.

Aber um zumindest mal auf die konkreten Fragen einzugehen:

Wie kommentiere ich innerhalb von Funktionen, blockweise oder garnicht ?

Ich machs blockweise. Andere haben schon geschrieben, dass sie es (wegen CleanCode) gar nicht machen.

Kommentiere ich rein private Klassenvariablen?

Kommt darauf an. Man muss sicher nicht stur und zum Selbstzweck jede einzelne (Klassen-)Variable kommentieren.

Gibt es da Richtlinien oder Tools ähnlich FxCop oder Literatur?

Es gibt da sicher die verschiedensten Richtlinien. Aber es gibt ebenso sicher nicht die eine ultimative Richtlinie. Das gleiche gilt für Literatur.

Es gibt auch sicher diverse Tools. Ich habe z.B. mal eins geschrieben, um das Verhältnis von Kommentarmenge zu Codemenge zu ermitteln. Aber außer sehr formalen Prüfungen kann man mit Tools nichts machen. Jedenfalls gibt es keine Möglichkeit automatisiert zu prüfen, ob sinnvoll und nützlich kommentiert wurde. Die Möglichkeiten des Tool-Einsatzes für diesen Zweck solle man daher nicht überschätzen.

Hallo zusammen,

davon abgesehen, wurde das Thema schon in Sollte alles im Code kommentiert werden? ausführlich behandelt.

Bitte hier nicht nochmal alles wiederholen und neu aufrollen, was schon in dem anderen Thread behandelt wurde.

herbivore

Hallo Herbi,
Nett wie immer..
Ich neige ja dazu die blockweisen Kommentare in Funktionen gleich zu Regions zu machen.
Den Thread kannte ich nich, TUT MIR LEID !
Mich interessieren unterschiedliche Ansichten halt da ich vermute die ein oder andere ist besser als meine bzw. ich bin mit meinem Kommentarverhalten einfach noch nicht so zufrieden. Ich merke das mir meine eigenen Kommentare nicht wirklich helfen wenn ich ein Projekt ein paar Monate nicht mehr angefasst habe.
Ich hab über Kommantare nie so richtig intensiv nachgedacht, das hat sich einfach so entwickelt.
Ich hab etwas gegoogelt und nichts richtig sinnvolles gefunden und deswegen hier
einfach mal nach den Best Practices der Commnity Entwicker gefragt.
Ich versteh ja das du auf deiner Seite hier nicht alles doppelt und dreifach haben willst, nix desto trotz frohe Ostern!

@All:

Ich finde, um das Verhältnis und die Art Code/Kommentierung zu sehen, sind auch größere Projekte für die ein immerwährendes Verständnis wichtig sein sollte,

kann sich ja mal den Source-Code und die Kommentare von PostSharp / AForge.net oder SharpDevelop ansehen.