Geschrieben von: Bernhard Spuida
Kategorie: Dokumentation
This printed page brought to you by AlphaSierraPapa
"Kommentare brauche ich nicht, ist doch eh klar was passiert" — Zwei Monate später: "Häh???". Käufer der Komponente: "Und wie bitte soll ich das aufrufen?" — wenn wir mit unseren Softwarekomponenten erfolgreich sein wollen, müssen sie leicht verwendbar sein. Wenn wir in einem Team Software entwickeln, müssen unsere Kollegen mit unserem Code ihre eigenen Aufgaben erledigen können. Wir haben in beiden Fällen zwei Möglichkeiten:
Möglichkeit 2 ist doch entschieden attraktiver, oder nicht? Traditionell ist das Schreiben von Dokumentation nicht der Teil des Entwicklungprozesses der am liebsten erledigt wird. Aber seit im Rahmen von .NET die Programmiersprache C# eingeführt wurde geht das (fast) von selbst. An die Javaprogrammierer die das hier lesen: ich kenne JDOC — aber hier geht es um C#, klar? ;-)
Für die Beispiele in diesem Artikel wird das .NET Framework SDK, sowie wahlweise Visual Studio.net oder SharpDevelop und/oder NDoc benötigt.
Ich weiß aus eigener langer Erfahrung (siehe Autoreninfo), daß man als Programmierer dazu neigt seine eigenen Programme nicht zu dokumentieren — man hat das ja selbst geschrieben, daher weiß man ja was im Code passiert? Falsch!
Nach einer erschreckend kurzen Zeit kennt man seinen eigenen Code ohne Dokumentation nicht mehr. Wie geht es dann einem Kunden der unser Control/unsere Bibliothek gekauft hat? Wenn wir unsere Software erfolgreich verkaufen wollen, muß sie ohne grossen Aufwand anwendbar sein. Dokumentation ist der Schlüssel dazu. Hier geht es nicht um Endbenutzerhandbücher, sondern um Dokumentation für Programmierer in unserem Team, Programmierer als Kunden unseren Codes.
Mal ehrlich: wäre ein grosses Projekt wie .NET ohne Dokumentation erfolgreich? Wäre Deine ActiveX Control ohne Dokumentation zu verkaufen — und sei es nur um wenige Dollar? Verwendest Du gerne Bibliotheken oder Komponenten ohne jegliche Dokumentation?
Die Antwort ist in allen Fällen nein. Trotzdem wird Dokumentieren der Schnittstellen und Funktionsweise meist als lästig empfunden.
Ein Beispiel warum Dokumentieren Sinn macht:
#!/usr/bin/perl -s
## Ian Goldberg <ian@cypherpunks.ca>, 19980817
$f=$d?-1:1;4D=pack(C',33..86);$p=shift;
$p=~y/a-z/A-Z/;$U='$D=~s/.*)U$/U$1/;
$D=~s/U(.)/$1U/;';($V=$U)=~s/U/V/g;
$p=~s/[A_Z]/$k=ord($&)-64,&e/eg;$k=0;
while(<>){y/a-z/A-Z/;y/A-Z//dc;$o.=$_}$o='X'
while length($o)%5&&!$d;
$o=~s/./chr(($f*&e+ord($&)-13)%26+65/eg;
$o=~s/X*$//if $d;$o=~~s/.{5}/$& /g;
print”$o/n”;sub v{$v=ord(substr($D,$_[0]))-32;
$v>53?53:$v}
sub w{$D=~s/(.{$_[0]})(.*)(.)/$2$1$3/}
sub e{eval”$U$V$V”;$D=~s/(.*)([UV].*[UV])(.*]/$3$2$1/;
&w(&v(53));$k?(&w($k)):($c=&v(&v(0)),$c>52?&e:$c)}
Das ist kein 'Spaghetticode' — das Programm läft linear ohne Verzweigungen ab. Trotzdem geht die Verständlichkeit gegen Null. Die erläuterte Version findet sich unter den Links im Artikel 'The fine Art of Commenting' (Ich weiß, manche werden es als fies empfinden daß ich in einem C#-Artikel ein Perl-Programm als Beispiel verwendet habe — auf Wunsch kann ich auch genauso unverständliche Beispiele in anderen Sprachen liefern).
Aber es gibt Auswege — automatisierte Dokumentationssysteme. Wir brauchen 'nur noch' unseren Code kommentieren und der 'Rest passiert von selbst'.
Wir können drei Arten von Kommentaren unterscheiden, die regelmäßig in der täglichen Programmierpraxis auftreten:
Alle drei Arten Kommentare sind wichtig für den Erfolg eines Projektes. Dokumentierende Kommentare sind sowohl innerhalb des Teams als auch für die Käu;fer der Software wichtig. Funktionale Kommentare sind innerhalb des Teams das Lebenselixir, erklärende Kommentare sind für alle wichtig: Uns selbst, das Team, die Kunden.
In diese Kategorie fallen Kommentare, die die Entwicklung des Projektes/des Files wiederspiegeln. Dazu gehören:
Derartige Kommentare können von Hand eingefügt werden. Da dies jedoch ein überaus fehleranfälliger Prozess ist, sollte man so weit möglich dafür die Platzhalter eines Versionskontrollsystems wie Visual SourceSafe, CVS oder ARCH verwenden. Je nach Vorliebe. Diese Platzhalter werden automatisch auf die jeweils aktuellen Werte gesetzt.
Funktionale Kommentare dienen einem Zweck: den Entwicklungsprozess effizienter zu gestalten. Sie beschreiben weder den Entwicklungsprozess wie es dokumentarische Kommentare tun, noch die Funktionsweise des Codes wie es erklärende Kommentare tun.
Sie dienen der Kommunikation innerhalb eines Entwicklerteams — mitunter sogar als Notizen an sich selbst. Häufigster und offensichtlichster Punkt in dieser Kategorie sind TO DOs. Andere funktionale Kommentare wären zum Beispiel:
Diese Sorte Kommentare sollte sparsam verwendet werden, auch wenn sie wichtig sind. Nicht jede Kleinigkeit verdient derartige Aufmerksamkeit.
Besonders bei dieser Art Kommentare ist es wichtig, in sich konsistent zu bleiben — entweder 'TODO', To do', 'ToDo', oder was auch immer, Hauptsache alle Teammitglieder halten sich an die Regelung. Dadurch wird sichergestellt daß alle mit einer einfachen Suche in ihrem jeweiligen Lieblingseditor alle entsprechenden Stellen im Code finden.
In diese Kategorie fallen auch alle beseitigten Fehler. Hier sollte das 'Wer', 'Was' und 'Wann' festgehalten werden. Man könnte jetzt natürlich argumentieren daß derartige Kommentare unter 'dokumentarisch' fallen, aber da die Fehlerbeschreibung hierher gehört, gehört auch der Bericht über seine Beseitigung hierher.
Jetzt kommen wir zum Herz des erfolgreichen Softwareprojekts — der Erklärung wie es funktioniert. Wenn wir Software lediglich aus der Sicht eines Endanwenders betrachten, benötigen wir das alles nicht. Wollen wir unsere APIs anderen Programmierern — in unserem Team oder als Kunden — zugänglich machen, so haben wir nur eine Wahl: Dokumentation. Ohne Erklärung von 'Was' und 'Wie' wird unser genialer Code nie akzeptiert oder erfolgreich verwendet werden. Außer natürlich wir haben ein Produkt für Endbenutzer geschrieben, sagen wir ein Officepaket —aber wieso gibt es auch da meterweise Bücher 'für Gummies' (aus urheberrechtlichen Gründen geändert)? Und wieso verdienen andere an solchen Büchern, nicht wir? Für uns als 'Programmierer für Programmierer' ist das Ganze zum Glück einfacher: Kommentare einfügen und unser Dokumentationssystem erledigt den Rest für uns.
Die leidige Aufgabe, unsere Interfaces zu dokumentieren wird uns zum Glück durch das .NET Framework (genauer C#) sehr erleichtert. Wir müssen 'nur noch' unseren Code mit Kommentaren in einem speziellen Format versehen und den Rest erledigt der Compiler, die IDE oder Software wie NDoc. Dazu mehr im nächsten Abschnitt.
Diese 'magischen' Kommentare enthalten XML-Tags mit bestimmten Schlüsselworten. Sie folgen einem bestimmten Muster:
///<exception cref="BogusException"> ; ///Diese Exception wird bei einem Fehlalarm ausgelöst. ///<see cref="ExceptionHandling" /> ///</exception>
Wir sehen als erstes daß alle Kommentarzeilen mit drei statt zwei 'Slashes' beginnen. Als zweites sehen wir daß wir uns an die Regeln für wohlgeformtes XML halten müssen, also sich die Tags nicht 'überkreuzen' dürfen. Weiters sehen wir, daß die Tags Attribute besitzen können, hier jeweils Verweise. Die XML-Kommentare in .NET lassen sich in zwei Kategorien unterteilen:
Die Kategorie-Tags dienen zur Erstellung von Einträgen in der generierten Dokumentation. Sie entsprechen den Interfaces, Parametern etc. Die Formatierungs-Tags erzeugen Verweise, erstellen Listen etc.
Die neun Kategorie-Tags sind in alphabetischer Reihenfolge:
| Tag | Verwendung | Attribute |
|---|---|---|
| example | Anwendungsbeispiel für das jeweilige API-element. Verwendet meist das <code> tag. | keine |
| exception | Beschreibt eine Exception die auftreten kann. | cref * |
| include | Bindet eine externe XML-Datei ein. | file, path * |
| param | Beschreibt einen Parameter einer Methode oder Eigenschaft | name * |
| permission | Gibt die Zugangsberechtigungen bzw. die Gültigkeit (Scope) eines Typmitglieds wieder | cref * |
| remarks | Beschreibt einen Typ oder eine Klasse | keine |
| returns | Gibt den Rückgabewert einer Methode wieder | keine |
| seealso | Gibt einen Verweis auf verwandte Themen | cref * |
| summary | Beschreibt Typmitglieder wie Methoden, Eigenschaften, Felder | keine |
Die mit einem Sternchen versehenen Attribute werden vom Compiler auf Gültigkeit geprüft, da sie im Sourcecode vorhandenen Elementen oder Querverweisen auf andere XML-Kommentare entsprechen.
Der beim Tag <include> als path angegebene Pfad muss als 'XPath' angegeben werden, also der XML-Notation für Pfade in XML-Dateien folgen. Man beachte die Verwendung von einfachen und doppelten Anführungsstrichen. Sie muß genauso erfolgen! Im konkreten Fall ist ein <include> folgendermassen zusammengesetzt:
///<include file='dateipfad\dateiname' path='tagpfad[@name="id"]' />
Ein konkretes Beispiel könnte folgendermaßen aussehen:
///<include file='doku\xml\Meineklassedoku.xml' path='Doku/MeineKlasse[@name="Foo"]/*' />
Der Pfad zur Datei ist nicht gleich dem Tagpfad! Ersterer kann relativ oder absolut in der üblichen Notation für Dateisystempfade angegeben werden. Letzterer gibt das Elternelement der einzufügenden Kommentare im eingebundenen XML-Dokument an, da in einem eingebundenen Dokument mehrere Texte für unterschiedliche Einbindestellen enthalten sein können. Bezüglich Feinheiten im Aufbau von XPaths sei an dieser Stelle auf die Dokumentation zum .NET Framework SDK verwiesen. Für das Beispiel könnte also die Datei Meineklassedoku.xml wie folgt aufgebaut sein:
<Doku>
<MeineKlasse name="Foo">
<summary>
Hier steht der Text, der Foo erklärt.
</summary>
</MeineKlasse>
<MeineKlasse name="Bar">
<summarys>
Und nun zu etwas völlig anderem...
</summary>
</MeineKlasse>
</Doku>
In der daraus generierten XML-Datei steht dann der <summary> Eintrag der unter der id mit Namen "Foo" gefunden wurde.
Die elf Formatierungs-Tags, ebenfalls in alphabetischer Reihenfolge:
| Tag | Verwendung | Attribute |
|---|---|---|
| c | Text wird als einzeiliger Sourcecodeauszug formatiert | keine |
| code | Für mehrzeilige Sourcecodeauszüge | keine |
| description | Beschreibung | keine |
| item | Punkt in einer Liste | keine |
| list | Liste | type |
| listheader | Listenkopfzeile | keine |
| para | Fügt einen Absatz ein (wie <p> in HTML) | keine |
| paramref | Zeichnet einen Text als Parameter aus. | name * |
| see | Fügt einen Verweis innerhalb eines XML-Kommentars ein | cref * |
| term | Begriff, der durch <description> definiert wird | keine |
| value | Beschreibt eine Eigenschaft | keine |
Diese Tags erklären sich eigentlich fast alle von selbst. Lediglich auf die Listen wollen wir näher eingehen, da dafür das Zusammenspiel mehrerer Tags nötig ist. Es gibt für das Attribut 'type' drei zulässige Werte: table, number, bullet. Damit wird das Aussehen der Liste bestimmt. Nun zu einem Beispiel das den Aufbau einer Liste verdeutlicht:
///<list type ="bullet"> ///<listheader> ///<term>Listentitel</term> ///<description>Teil 2 des Titels</description> ///</listheader> ///<item> ///<term>Eintrag 1:</term> ///<description>Beschreibung 1</description> ///</item> ///<item> ///<term>Eintrag 2:</term> ///<description>Beschreibung 2</description> ///</item> ///</list>
Ok, noch einer: <paramref> kann auch in einer alternativen Form verwendet werden:
///<paramref>Foo</paramref> macht 'bar'. ///oder so: ///Diese Funktion parst <paramref="baz" /> zur Weitergabe als Argument fuer <c>frobnicate(parsedBaz)</c>.
Um ein wenig mit XML-Kommentaren und ihrer Umsetzung in HTML(-Help) zu experimentieren gibt es von Lutz Roeder das Tool 'Documentor', das XML-Kommentare interaktiv in das entsprechende HTML umsetzt:
Die so erzeugten Kommentare können über die Zwischenablage in den Quelltext übernommen werden. Dieses Tool findet sich unter dem entsprechenden Link am Ende des Artikels.
Der C# Compiler selbst hat eine Option '/doc:outputfile'. Diese Option sorgt lediglich dafür daß die XML-Kommentare in eine XML-Datei namens outputfile extrahiert werden. Ebenso können wir in Visual Studio .net die Dokumentation extrahieren lassen. Dazu müssen wir die Eigenschaften für das Projekt aktivieren, in den Konfigurationsdialog wechseln, die 'build'-Option wählen und die Eigenschaft 'XML-Dokumentationsdatei' auf den gewünschten relativen Pfad setzen.
Wir wollen aber eine interaktiv als (HTML)Hilfedatei verfügbare Dokumentation der Schnittstellen. Was also tun?
Man kann sich nun entweder selbst ein Tool schreiben das die notwendige Umwandlung vornimmt (vorausgesetzt man ist in XML/XSLT entsprechend versiert und hat spezielle Anforderungen an die erzeugte Dokumentation), auf das im unten angeführten MSDN-Artikel vorgestellte Tool zurückgreifen oder NDoc, ein Open Source Tool zur Dokumentationsgenerierung analog zu JDoc für Java, verwenden.
Falls die Open Source IDE #develop verwendet wird, ist NDoc bereits integriert. Zur Erstellung der HTML-Dokumentation muß hier bei den Projektoptionen die Option XML-Doku generieren auf dem zweiten Tab aktiviert werden und zur Erstellung der eigentlichen Dokumentation aus dem Kontext- oder Compiler-menü der Punkt 'Dokumentation generieren' ausgewählt werden.
NDoc ist sowohl innerhalb von #develop wie auch in der eigenständigen Version mit einer graphischen Benutzeroberfläche versehen. Will man allerdings HTML Help Dateien generieren, so muß das entsprechende SDK von Microsoft installiert sein.
Na, ist doch nicht so schwierig, oder? Wer seine Kommentare in XML einfügt spart sich viel lästige Dokumentationsarbeit im Nachhinein. Diese Zeit kann man dann für neue coole Projekte, Urlaub oder auch Beschwerden über undokumentierte APIs in den Projekten anderer nutzen.
This printed page brought to you by AlphaSierraPapa
A Brief History of C#
http:/www.aspheute.com/artikel/20000713.htm
Einfaches XML-Auslesen in .NET
http:/www.aspheute.com/artikel/20001117.htm
Erstellen von HTML Help Dateien
http:/www.aspheute.com/artikel/20020617.htm
XML-Daten verarbeiten mit XSLT
http:/www.aspheute.com/artikel/20020116.htm
Documentor for .NET (Lutz Roeder)
http://www.aisto.com/roeder/dotnet/
Microsoft HTML Help Downloads
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
Ndoc Homepage
http://ndoc.sourceforge.net/
SharpDevelop (#develop)
http://www.icsharpcode.net/OpenSource/SD/
Tech Note: The fine Art of Commenting
http://www.icsharpcode.net/TechNotes/
XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files
http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/xmlc.asp
©2000-2006 AspHeute.com
Alle Rechte vorbehalten. Der Inhalt dieser Seiten ist urheberrechtlich geschützt.
Eine Übernahme von Texten (auch nur auszugsweise) oder Graphiken bedarf unserer schriftlichen Zustimmung.