Nicht nur wenn ein Projekt größer wird, sondern prinzipiell immer sollten sowohl Quellcode als auch das Projekt an sich dokumentiert werden, damit spätere Entwickler weniger Einarbeitungszeit benötigen und nicht erst den Quellcode durcharbeiten müssen, um das Projekt zu verstehen.
Heute möchte ich auf einen Teil der Dokumentation eingehen, manchmal auch als technische Dokumentation bezeichnet (obwohl sich darüber die Geister streiten, was eine technische Dokumentation genau definiert, wie man hier [1], hier [2] oder hier [3] nachlesen kann.), dem Quellcode.

Unterstützung erhält man dabei durch eine Software namen Doxygen. Diese kann anhand der Projektstruktur mit Bibliotheken, Klassen und Verzeichnissen eine ansehliche Dokumentation erstellen.
Wichtig ist, dass der Quellecode im Javadoc [4] Stil kommentiert wird. Ein Beispiel:

Schnell erkennt man, dass ich die Parameter eine Funktion calc mit @param beschreibe, davor kommt eine allgemeine Funktionsbeschreibung, um die Aufgabe der Funktion zu verdeutlichen. Sollte die Funktion keinen Rückgabewert haben, lässt man @return einfach weg. Der Parameter @see beschreibt einen Verweis auf eine andere Funktion, die evtl. mit dieser im Zusammenhang steht oder ähnliche Funktionalität aufweist.

Der Kopf einer Klasse sollte immer folgendes Format besitzen (die meisten IDEs wie z.B. Eclipse generieren diesen automatisch):

Nachdem ihr jetzt grundlegend wisst, wie eure Klassen “lesbar” gemacht werden, geht es daran, Doxygen [5] zu konfiguieren. Ich arbeit selbst am Mac und werde daher hier auf die Macversion eingehen, habe aber auch mit der Windowsversion gearbeitet und es gibt keinen Unterschied.
Öffnet Doxygen und startet den Wizard. Viele Sachen sollten selbsterklärend sein, hier aber einige Tips oder Fallstricke:

Step 1
Gebt hier den Pfad zum Installationsordner (!) von Doxygen an.

Project version or id
Hier müsst ihr immer manuell eine neue Version der Doku eingeben, kann ich nur empfehlen, wenn ihr an einem Projekt arbeitet, dass sich kontinuierlich (im Team) entwickelt.

Specify the directory to scan for sourcecode
Hier wird der eigentliche Projektordner mit euren Klassen, Bibliotheken usw. angegeben.

Doxygen Wizard erster Schritt

-> Nächster Schritt

Select the desired extraction mode
Ich wähle fast immer “Documented entities only”, dann erkennt ihr schnell, ob noch Klassen dokumentiert werden müssen, wenn diese nicht in der Doku auftauchen. Der Haken bei “Include cross-referenced source code in the output” gefällt mir, denn dann werden in der Doku alle Funktion aufgelistet die auf die aktuelle Funktion zugreifen.

Select programming language to optimize the results for
Hier die entsprechende Sprache wählen oder eine ähnliche. Für Objective-C habe ich z.B. mit “Java or C#” gute Erfahrungen gemacht. Einfach auch etwas ausprobieren.

Zweiter Schritt im Wizard von Doxygen

-> Nächster Schritt

Select the output format(s) to generate
Ich möchte in meinen Dokus immer links einen Frame mit Baumnavigation (“with frames and a navigation tree”) haben. Auf die Suchfunktion verzichte ich meistens, hat teilweise Probleme beim Generieren der Doku erzeugt. Ausgabe als Latex ist sehr toll, es entsteht anschließend einer verlinkte refman.tex, welche auf dem Mac z.B. mit MacTeX [6] und der eingabe “make” im Terminal in eine PDF umgewandelt werden kann.

Dritter Schritt im Wizard von Doxygen

-> Nächster Schritt

Im letzten Schritt kann man sich entscheiden, ob Diagramme der Klassenstrukturen erzeugt werden sollen. Lohnt sich prinzipiell nur, wenn es viele Klassenabhängigkeiten im Projekt gibt. Daher Punkt 2 oder, falls dem nicht so ist, Punkt 1 wählen.
Nachdem der Wizard durchgestanden ist, kann gerne im Reiter “Run” auf den Button “Run Doxygen” gedrückt werden. Vergesst nicht, eure Profildatei zu speichern!
Geht nichts schief, bekommt ihr, wenn ihr den Button “Show HTML Output” mit eurer Maus malträtiert, eine HTML-Seite eurer Doku im Browser präsentiert. Das sieht dann so aus:

Ausgabe der HTML Doku

Kommen wir nun zu einigen Experteneinstellungen, die ihr im zweiten Reiter findet. Dort sind einige Einstellungen versteckt, die teilweise sehr wichtig sind.

-> Project

OUTPUT_LANGUAGE
Sprachumstellung auf Deutsch, so dass einige Standardbegriffe in der Doku auf Deutsch erscheinen (“File List” -> “Auflistung der Dateien”). Es sind aber noch nicht alle Begriffe übersetzt.

STRIP_FROM_PATH
Wollt ihr in eurer Doku nicht immer my/project/with/long/path/to/the/classes/Hello.java zu stehen habe, dann gebt dort den Pfad ein, der abgeschnitten werden soll. (in diesem Falle “my/project/with/long/path/to/the/classes”).

SEPARATE_MEMBER_PAGES
Seid ihr ein eifriger Kommentator und schreibt auch was zu euren Klassenvariablen, könnt ihr eure Romane auf einzelnen Seiten ausgeben lassen.

-> Build

EXTRACT_ALL
Soll wirklich alles und nicht nur dokumentierte Klassen bearbeitet werden, setzt ihr hier einfach einen Haken. Dann werden aber wirklich alle (!) Dateien, Variablen und Methoden in die Doku aufgenommen. Das kann auch noch verfeinert werden, indem ihr EXTRACT_PRIVATE explizit auswählt, so dass auch private Klassenvariablen ausgelesen werden.

-> Input

INPUT_ENCODING
Hier tragt ihr am besten “ISO-8859-1″ ein, wenn eure Dateien nicht im UTF-8 Format abgespeichert sind, sonst bekommt ihr in eurer Doku nur Zeichensalat.

EXCLUDE
Sehr wichtige Einstellunge. Oftmals liegen in einem Projekt Testdateien oder -klassen, die man ungern in der Doku haben möchte. Klar kann man anwählen, dass man nur dokumentierte Dateien aufnehmen möchte, aber die Holzhammermethode ist das explizite ausschliessen bestimmter Dateien.

-> HTML

HTML_HEADER, HTML_FOOTER, HTML_STYLESHEET
Über HTML_HEADER kann eine eigene HTML-Datei für den Kopf festgelegt werden, das gleiche gilt für den Footer. HTML_STYLESHEET bietet die Möglichkeit, die Standard-CSS von Doxygen zu verändern bzw. zu überschreiben. Vergesst nicht, eure verlinkten Dateien aus externen HTML-Dateien bzw. die CSS in den Zielordner eurer Doku zu kopieren.

TREEVIEW_WIDTH
Hier könnt ihr die Breite des linken Frames mit der Baumstruktur festlegen. Oftmals sind 250px einfach zu schmal und bei heutigen Auflösungen auch unnötig klein.

So sähe dann übrigens die PDF Datei aus, wenn ihr sie durch MacTeX jagt:
Dokumentation

Was heisst “technische Dokumentation” für euch? Womit dokumentiert ihr eure Projekte und habt ihr Tips für Doxygen oder was man anders machen könnte? Womit bildet ihr eure Datenbankmodelle ab und was habt ihr für Erfahrungen damit? Über einen Kommentar würde ich mich freuen!

Quellen

• [1] Die Technische Dokumentation im Wandel: http://www.transline.de/transline-tecNews/technische-dokumentation-im-wandel-anforderungen-redaktionssysteme-docuglobe
• [2] Was ist Technische Dokumentation?: http://www.comet.de/technische_redaktion/technische_dokumentation.php
• [3] Checkliste zur Qualitätssicherung Technischer Dokumentation: http://www.indoition.com/de/qualitaet-software-dokumentation.htm
• [4] Javadoc - was ist das und wie nutze ich es?: http://de.wikipedia.org/wiki/Javadoc
• [5]
  Source code documentation generator tool: http://www.stack.nl/~dimitri/doxygen/
• [6] The MacTeX-2009 Distribution: http://www.tug.org/mactex/2009/

Related posts:

1. Tutorial: ExternalInterface – Zusammenspiel von SWF und JavaScript Manchmal ist es nötig, SWF Dateien mit dem aktuellen Container...
2. Tutorial: Mehrsprachige Anwendungen in Flex 3 Wer schon einmal vor der Aufgabe stand, eine Flex Projekt...

Ähnliche Artikel bereitgestellt von Yet Another Related Posts Plugin.

Mehr Beiträge aus meinem Blog als RSS? Hier abonnieren:

Geschrieben am Donnerstag, 26. November 2009 und abgelegt unter Tutorials, Webentwicklung. Verfolgen Sie die Diskussion zu diesem Beitrag per RSS 2.0 Feed. Sie können diesen Beitrag kommentieren oder einen Trackback von Ihrer eigenen Webseite setzen.