Programm Dokumenta-was?

[Mcolli]

In diesem Thread wollte ich eine, evtl. schon bekannte, gute Möglichket der Programmdokumentation beschreiben, die auf Quellcode-Kommentaren von .Net Anwendungen basiert und im Look einer Standart .Net-Dokumentation erscheint.

Dokumentation warum?

In vielen Unternehmen scheint mir, aufgrund enormen Zeitdrucks bei der Entwicklung kleinerer Anwendungen, keine Dokumentation-Pflicht zu bestehen. Daher stellt sich natürlich die Frage warum Dokumentieren.

Die Antwort ist Simpel:

Wenn man als Entwickler bei der Entwicklung einer Anwendung darauf bedacht ist zu den Klassen, Felder, Attributen und Methoden Kommentare vor deren Implentierung zu schreiben, sollten Designprobleme, wie eine Methode mit 5 Parametern von denen 3 zu 99% mit null belegt werden, vorzeitig erkennbar sein.

Ausserdem erleichtert eine solche Annhährung an ein Problem meistens nicht den Blick für das große Ganze zu verlieren. Somit ist der Quellcode leicht verständlich und wenn man selbst oder ein anderer eine modifizierung des Programms vornehmen soll, kann dies schon nach kurzem Einlesen ohne IDE erfolgen.

Wie wirds gemacht?

Zunächste ich wichtig, dass man alle nötigen XML-QuellCode Kommentare setzt. Die gehschiet, wenn man den Cursor über Beispielsweise eine Mehtode setzt und dann 3 mal "/" ohne " schreibt. In Visual-Studio wird damit für einen kommentierungsrelevanten Teil ein abschnit mit den nötigen XML-Tags erzeugt. Dieser muss dann zwischen den Tags mit Sinn gefüllt werden.

Bei den Eigenschaften des Projekts im Projektmappenexplorer (Rechtsklick auf das entsprechende Projekt und dann "Eigenschaften") kann man dann unter dem Karteireiter "Erstellen" die Checkbox "XML Dokumentatiosdatei" aktivieren und einen Ausgabe Pfad bestimmen.

Die Umwandlung erfolgt dann mittels eines Zusatzprogramms "Sandcastle"

zu finden unter:

Sandcastle - Documentation Compiler for Managed Class Libraries

Dies ist ein Komandozeile basieretes Projekt das mittels Reflektion und der XML Dokumentationsdatei eine tolle Dokumentation aufbereitet.

Um nicht in alter Dosmanier alle Parameter per Komandozeile anzuhängen gibts die GUI Lösung in Verbingung mit oben genannten Sandcastle:

(Sandcastle Help File Builder)

Sandcastle Help File Builder

Letzten Endes kommentiert Ihr einfach den Quellcode erzeugt beim Buildvorgang wie obenbeschrieben die XML-Doku und erstellt eine neues "Sandcastle Help File Builder" Projekt, bei dem Ihr Eure Projektdatei unter "Documentation Sources" angebt und führt den Buildvorgang für das "Sandcastle Help File Builder" Projekt aus.

Ein gutes schnelles Tutorium haben die auch (bezieht sich auf das erstellen der Helpfile ... nach Installation der Software (die Links oben) und Kommentierung des Quellcodes des eigen Projektes)

http://www.ewoodruff.us/shfbdocs/html/

[lbm1305]

Nettes Thema, doch sollte Code gar nicht kommentiert werden !!

Warum das?

1.) Code sollte selbsterklärend sein. Das schließt Methoden, Klassen etc. ein.

2.) Ein Entwickler sollte bestrebt sein, seinen Code zu verbessern. Soll heißen, dass man Code klar und für jedermann verständlich schreiben sollte. Dazu gehört, dass man sich z.B. an die 5 Prinzipen (S.O.L.I.D) halten sollte. Dies wäre schon der erste Schritt zu einfachen Code.

Kommentare dienen als Vorwand, seinen Code nicht verbessern zu müssen, da dies ja über den Kommentar geregelt wurde.

EDIT: Wenn es wirklich nicht anders geht, dann ist ein Kommentar sinnvoll, solange es kein Roman ist.

Eine Softwaredokumentation ist aber im Gegensatz sinnvoll :-)

Bearbeitet 23. Februar 2010 von lbm1305

[Mcolli]

Ich rede nicht von Inline-Kommentaren sondern Klassen-Kommentaren(Was kann die Klasse), Methoden Signatur Kommentaren (was macht die Methode, welche Parameter, was gibts sie Zurück), Enum-Kommentaren, Propertie Kommentaren usw.

Am Ende sollte man sowas erstellen können:

MSDN Auszug

Solche Kommentare nicht zu machen ist sehr schlechter Programier-"Stil".

Ich kann Dir aus eigener Erfahrung sagen, ein Programm, das man nicht selber geschrieben hat, aufzubohren dauert ewig wenn diese Kommentare nicht gemacht werden.

Ausserdem gibts nen guten Grund dafür, das Visual Sudio die nötigen Kommentare-Blöcke per Autoergänzung anlegt wenn man an der richtigen Stelle 3x "/" ohne " schreibt.

[lbm1305]

Die XML-Kommentare sehe ich wichtig an, wenn man Bibliotheken zur Verfügung stellt. Bestes Beispiel war (ich weiß nicht, ob es noch so ist) der MySQL Connector für .NET Da war gar nichts "dokumentiert".

Wenn man Code sauber schreibt, man anhand der Benennung der Klassen und Methoden erkennt, was die Klasse macht und die Klassen so klein wie möglich hält (Single Responsibility Principle), dann braucht man (fast) keine Dokumentation in Form von XML-Kommentaren.

[TDM]

Die Umwandlung erfolgt dann mittels eines Zusatzprogramms "Sandcastle"

zu finden unter:

Sandcastle - Documentation Compiler for Managed Class Libraries

Ich nenn als Alternative mal noch Doxygen... :floet:

[Pointerman]

Ergaenzend moechte ich auch noch GhostDoc erwaehnen:

SubMain / GhostDoc - Simplify your XML Comments!

Das vereinfacht das Erstellen der XML-Kommentare noch einmal. (Rechte Maustaste auf die Methode/Klasse, Document this waehlen und ab geht die Luzi! )

Ich oute mich hiermit auch als grosser Doxygen-Fan.

Ich weiss nicht so genau was Sandcastle alles kann, aber Doxygen kann neben einer HTML-Doku auch LaTex-Dokumente erstellen und kann auch Diagramme erstellen, durch die man dann per Mausklick navigieren kann.