Hallo zusammen,

evtl. bin ich hier im falschen Bereich, ich bitte um Nachsicht und um verschieben in die Korrekte Kategorie.

ich stell mir schon seit geraumer Zeit die Frage wie ich ein Projekt, egal ob groß oder klein, logisch dokumentiere und kommentiere. So das ein projektfremder Entwickler den Code problemlos versteht und auch weiterentwickeln kann. Anscheinend hat jeder so seine eigene Art zu dokumentieren, so habe ich Codes da werden nur die Übergabeparameter beschrieben, jede zweite Zeile wird beschrieben oder es wird nur eine Klassenbeschreibung erstellt. Wenn ich mir selbst die Frage stelle welche Dokumentation gut wäre, würde ich sagen das jede Funktion beschrieben werden sollte, die Klasse ausführlich beschrieben sein sollte, eine Datenbankdokumentation mit den entsprechenden Schlüsseln. Die Schnittstellen sollten natürlich ebenfalls beschrieben sein.

Nun ist das ja immens viel Schreiblkram, wir macht Ihr das? Gibts evtl. Richtlinien an denen man sich entlang hangeln könnte?


Moderiert von Th69: Topic aus C# - Die Sprache verschoben am Fr 17.02.2012 um 23:07

Wenn man sauberen Code schreibt, sprich gute Bezeichner und Strukturen wählt usw., sind gar nicht so viele Kommentare im Code nötig. Leider sehe ich oft Abkürzungen und extrem kurze Bezeichner in fremden Quelltexten. Warum manche so sparsam mit Buchstaben umgehen ist mir nicht ganz klar, soo teuer sind Festplatten ja nun doch nicht , aber dadurch kann man viele Quelltexte kaum schnell überblicken.

Meine Bezeichner sind sehr oft 15 oder mehr Zeichen lang, aber dafür weiß man auch sofort was das für eine Klasse ist, was in einer Funktion passiert oder was in einer Variable drin ist. So habe ich auch nach längerer Zeit keine Probleme mich sehr schnell wieder in ältere meiner Quelltexte einzulesen.

Je größer das Projekt ist, desto mehr geht es aber vermehrt um die größeren Zusammenhänge und desto mehr muss man diese natürlich dokumentieren. Da gibt es z.B. Diagramme zur Übersicht und Beschreibungen der einzelnen Klassen.

1. Sprechende Bezeichner benutzen. Um so offensichtlicher die Bezeichnung umso weniger muss man kommentieren.

2. Dokumentiere nur die Sachen die nicht offensichtlich sind (ok nicht immer einfach zu entscheiden. Als Lone Programmer hat man da ein Problem wenn man kein weiteres Augenpaar zur Verfügung hat). Zum Beispiel der Ansatz jede Funktion zu beschreiben (wie du schreibst) führt üblicherweise nur dazu das man offensichtlichen Code beschreibt. Dem nächsten Maintainer deines Codes wird das auffallen und die Kommentare schnell für überflüssig halten und nicht mehr lesen. Dadurch entgeht ihm dann natürlich auch die relevante Dokumentation und du hast den Aufwand weitestgehend umsonst erbracht. Der Ansatz alles zu dokumentieren funktioniert nur wenn man sich die Msdn als Beispiel nimmt. Also wenn man auch Codebeispiel, Ausnahmen, Querbezüge etc. mitpflegt. Wenn du die entsprechenden Resourcen hast das zu tun nur zu. Ansonsten versuch es erst gar nicht

3. Wenn du die Funktionalität in einer Methode kommentierst schreibe nicht primär was die Methode tut sondern das Ziel der Methode und dann warum sie es auf dem implementierten Weg macht. Damit verhindert man das ein anderer Entwickler die Refactoringkeule auspackt um die Methode zu ~vereinfachen~. Oft gibt es aber einen Grund warum die offensichtlich einfache Lösung eben nicht funktioniert. Das sollte man auf jeden Fall dann auch hinschreiben.

4. Unittests für eine Methode sind die beste Dokumentation! Man versteht Code viel besser wenn man sieht wie er in einem kurzen knackigen Beispiel eingesetzt wird als mit trockener Doku. Wenn du unter Zeitmangel leidest und dich entscheiden musst zwischen Unittest und Codedokumentation entscheide dich für Unittest.

5. Benutze nicht Ghostdoc. Die Bequemlichkeit führt schnell dazu das die automatisch generierte Hilfe irgendwann nicht mehr sinnvoll überarbeitet wird und du hast wieder das in Punkt 2. beschriebene Problem.

6. Schreibe Kommentare in einer Sprache die du beherrschst. Wer schonmal englische Kommentare geschrieben vom einem polnischen Coder seinem italienischen Kollegen erklären mußte weiß warum!

Hallo Raorkon,

ich sehe es auch so wie jaenicke, daß Kommentare im Code selbst, so selten wie möglich sein sollten - nur wenn es evtl. um komplexe Algorithmen oder Formeln etc. geht.

Wichtiger sollten die Dokumentation zu den einzelnen Klassen (bzw. Schnittstellen) sowie den öffentlichen Methoden sein.
Dazu kann man ja im VS einfach über die Klasse/Schnittstelle bzw. Methode/Eigenschaft einfach "///" schreiben und VS erzeugt dann einen entsprechenden <summary>-Eintrag (plus evtl. weitere Tags, z.B. <param>).
Und hiermit läßt sich dann auch effizient weiterarbeiten (z.B. für Intellisense).

Und es gibt natürlich auch noch eine Reihe von Tools, welche einem dabei unterstützen, z.B.
GhostDoc
AtomineerUtils
sowie
SandCastle, um externe Hilfedateien (z.B. im CHM-Format) daraus zu erzeugen.

Edit: Ups, ich habe das "böse" Tool erwähnt *g*

Danke für eure Kommentare, ich finde es sehr interessant wie andere Entwickler Ihr Codes dokumentieren (oder auch nicht).

Im allgemeine finde ich das dieses Thema kaum behandelt wird, weder in irgendwelchen Büchern, Studium oder Lehrgängen.

Zusammengefasst sollte man Bezeichner einfach nur sprechend gestalten.

Ralf, deinen Rat werde ich beherzigen und meine zukünftigen Kommentare kurz und knackig halten.

Die Summary-Funktion nutze ich auch sehr gern da Sie für alle Funktionen eine einheitliche Form der Dokumentation vorgeben.