Sven Müller, Thomas Hornberger Software - Engineering Berufsakademie Horb Studiengang Informationstechnik 03 Florianstraße 15 72160 Horb musv@ba-horb.de hoth@ba-horb.de Abstract: Im Prozess der Softwareentwicklung ist ein Verzicht auf eine Dokumentation aus heutiger Sicht undenkbar. Der Zeitaufwand eines Programmierers für eine Dokumentation ist dem des eigentlichen Programmierens gleichzusetzen. Jedes Unternehmen fordert von seinen Mitarbeitern eine vernünftige und wieder verwertbare Dokumentation, um die immer kürzer werdenden Innovationszyklen meistern zu können. In dieser Arbeit wird auf die grundsätzlichen Vor- und Nachteile, sowie Probleme bei einer Software- Dokumentation eingegangen. Besonderes Augenmerk richtet sich auf die Kommentierung von Quellcode. Insbesondere hier wird in der Praxis häufig auf die Unterstützung von n gesetzt. Die Komponenten und Einsatzgebiete einiger wichtiger Werkzeuge werden beschrieben, sowie deren Effizienz anhand von Beispielen erläutert. Sven Müller, Thomas Hornberger 8.12.2005 Seite 1 von 26
Inhaltsverzeichnis 1. EINLEITUNG... 3 1.1 SINN UND NOTWENDIGKEIT VON DOKUMENTATIONEN... 3 1.2 KLASSIFIZIERUNG... 3 1.3 ENTWICKLUNGSPRINZIPIEN... 3 1.4 PROBLEME VON DOKUMENTATIONEN... 4 2 SELF DOCUMENTING CODE... 5 2.1 EINLEITUNG... 5 2.2 BEISPIEL... 5 2.3 VARIABLEN UND KONSTANTEN... 6 2.4 FUNKTIONEN... 6 2.5 DATENORGANISATION... 7 2.6 LAYOUT... 7 2.7 KONTROLLSTRUKTUR... 7 3. VERSCHIEDENE DOKUMENTATIONSWERKZEUGE... 8 3.1 EINLEITUNG... 8 3.2 DOC++... 8 3.3 KDOC... 9 3.4 CCDOC... 11 3.5 PERCEPS... 12 3.6 JAVADOC... 14 3.7 DOXYGEN... 17 4. FAZIT... 26 LITERATURVERZEICHNIS... 26 INTERNET-REFERENZEN... 26 Sven Müller, Thomas Hornberger 8.12.2005 Seite 2 von 26
1. Einleitung 1.1 Sinn und Notwendigkeit von Dokumentationen Gute Dokumentation unterstützt die Entwicklung von und den Umgang mit Software in hohem Maße. Sie bietet eine Anleitung für den Anwender und Endkunden im Umgang mit dem Produkt. In diesem Zusammenhang ist keinesfalls zu unterschätzen, dass die Zufriedenheit eines Kunden mit dem Produkt mit dem Verständnis für das Produkt ansteigt. Eine gute Dokumentation kann ein wertvolles Hilfsmittel bei der Präsentation der Software gegenüber potentiellen Kunden sein und als Entscheidungsgrundlage dienen, welche vorab begutachtet werden kann. Eine technisch fundierte, interne Dokumentation unterstützt das Entwicklerteam bei der Wartung und Weiterentwicklung der Software. Sie ist ein wichtiges Dokument innerhalb von internen und externen Prüfungen, wodurch das Entwicklerteam eine Kontrollfunktion für den Entwicklungsfortschritt des Produkts erhält. Die Projektdokumentation bildet eine gemeinsame Gesprächsgrundlage zwischen vielen am Produkt beteiligten Personen und Personengruppen. Zwischen Entwicklern beispielsweise ebenso wie gegenüber einem Kunden. 1.2 Klassifizierung Der organisatorische Ablauf einer Dokumentation lässt sich in zwei Bereiche unterteilen: - Interne Dokumentation: Diese Form der Dokumentation wird nicht veröffentlicht. Sie bleibt innerhalb der Firma beziehungsweise innerhalb des Entwicklungsteams. Ihre Funktion liegt in der Unterstützung der Entwicklung und Wartung des eigenen Softwareproduktes. - Externe Dokumentation: Die externe Dokumentation ist für die Veröffentlichung konzipiert und dient dem Anwender und Endkunden als Bedienungsanleitung für die Software. 1.3 Entwicklungsprinzipien Das nachfolgende Kapitel beschäftigt sich mit wichtigen Anhaltspunkten für eine gute und erfolgreiche Dokumentation von Softwareprodukten. Bei einer Dokumentation handelt es sich um einen Entwicklungsbegleitenden Prozess, die Ausarbeitung der Dokumentation muss mit der Entwicklung des Quellcodes Schritt halten. Weiterhin muss eine Orientierung an der beabsichtigten Zielgruppe erfolgen, deren Wissen und deren Einsatz der Dokumentation sind entscheidende Kriterien für die Gestaltung der Dokumentation. Neben der Dokumentation ist eine gute Kommentierung des Quellcodes zwingend erforderlich. Sven Müller, Thomas Hornberger 8.12.2005 Seite 3 von 26
Der Einsatz von grafischen Elementen ist unbedingt anzuraten, er erleichtert das Erfassen und Verstehen der Dokumentation deutlich. Dies gilt sowohl für Skizzen, Tabellenund Ähnlichem in allgemeiner Hinsicht als auch für domänenspezifische Visualisierungstechniken wie ER-Diagramme oder UML. Der Einsatz von Ein Einsatz von n empfiehlt sich, wenn dieser möglich ist. Der Vorgang gewinnt an Zeit und Effizienz und die Motivation für die Entwicklung der Dokumentation wächst. 1.4 Probleme von Dokumentationen Nachfolgend finden sich schwere Fehler bei der Dokumentationsentwicklung, welche den Nutzen der Dokumentation zumindest in hohem Maße schmälern: - Fachsprache: Eine Dokumentation darf höchstens jenes Maß an Fachsprache beinhalten, welches die Zielgruppe mit Sicherheit versteht. Demzufolge ist die diesbezügliche Gestaltung stark vom Anwender abhängig. Generell kann jedoch angeführt werden, dass leicht verständliche Sprache in den wenigsten Fällen ein Fehler ist. - Konsistenz: Eine in sich inkonsistente Dokumentation stellt ein erhebliches Problem bei deren Verwendung dar. Häufige Fehler in dieser Hinsicht liegen in fehlender Aktualität, in Unvollständigkeit und in Widersprüchlichkeit. - Gestaltung: In diesem Bereich können zwei unterschiedliche Arten von Fehlern gemacht werden. Zum Einen kann durch ein nicht ansprechendes Layout die Motivation der Verwendung deutlich herabgesetzt werden, und zum Anderen stellen inhaltliche Fehler wie ein nicht vorhandenes Stichwortverzeichnis ein Hindernis in der Benutzung dar. Sven Müller, Thomas Hornberger 8.12.2005 Seite 4 von 26
2 Self documenting Code 2.1 Einleitung Mit dem Anwachsen an Quellcode in einem Projekt wird die Übersicht schlechter. Deswegen ist es sinnvoll seinen Quellcode in einer gewissen Form zu schreiben. Diese Form nennt man auch Self-documenting Code. Unter Self-documenting Code versteht man die Generierung von Quellcode mit einer sinnvollen und möglichst selbsterklärenden Syntax. Dies bezieht sich auf das Layout sowie auf die Wahl von Klassen-, Funktions- und Variablennamen. 2.2 Beispiel Der durch self-documenting code hinsichtlich der Lesbarkeit und des Verständnisses entstehende Vorteil lässt sich gut anhand eines Beispiels nachvollziehen. Die folgende Tabelle zeigt zweimal den, in Bezug auf seine syntaktische Bedeutung, gleichen Code. for(i=1;i<=num;i++){ MeetsCriteria[i]=tru e; for(i=2;i<=num/2;i++ ){ j=i+i; while(j<=num){ MeetsCriteria[j]=fal se; j=j+i; }} for(i=1;i<=num;i++){ if(meetscriteria[i]) System.out.println(i ); for(primecand=1;primecand<=num;primec and++) IsPrime[primeCand]=true; for(factor=2;factor<=num/2;factor++){ factnumber=factor+factor; while(factnumber<=num){ IsPrime[factNumber]=false; factnumber=factnumber+factor; } } for(primecand=1;primecand<=num;primec and++) if(isprime[primecand] System.out.println(primeCand); Sven Müller, Thomas Hornberger 8.12.2005 Seite 5 von 26
Die rechte Version ist ungeachtet der oben stehenden Tatsache deutlich besser lesbar und verständlich. Durch die Verwendung von sprechenden Variablenbezeichnern, durch die Einrückungen und durch die Trennung des Initialisierungsteils mittels einer Leerzeile wurde wesentlich besser kommentierter Code geschrieben, ohne eine einzige Zeile klassischen Kommentar verwendet zu haben. Es folgt nun ein weiteres Beispiel: Falsch: int status = NEW; // der Integervariablen status wird der Wert der Konstante NEW zugewiesen Richtig: int status = NEW; // Art der Benutzeranmeldung 2.3 Variablen und Konstanten Der Bezeichner ist so zu wählen, dass er die Aufgabe beziehungsweise Verwendung der Variablen oder Konstanten beschreibt. Gute Beispiele sind NOfUsers, maxvalue oder currentproduct. Bei Schleifenzählern oder in ihrer Verwendung klar erkennbaren Hilfsvariablen kann hiervon Abstand genommen werden. Insbesondere bei codierten Bedeutungen ist auf gute Bezeichner zu achten, wie am nachstehenden Beispiel gut erkennbar ist. Beispiel: static final int NEW_USER = 1, MODIFY_USER = 2,... Eine subjektiv sehr unterschiedlich wahrgenommene Kommentierungsvariante ist die im Allgemeinen als Hungarian Notation bezeichnete Möglichkeit, den Typ der Variablen im Namen durch ein oder mehrere dem eigentlichen Bezeichner vorangestellte Symbole zu kennzeichnen. Als interessante Variante sei sie jedoch angeführt. 2.4 Funktionen Funktionen werden durch einen sprechenden Namen bezeichnet, dieser muss ihre Aufgabe beschreiben. In diesem Sinne gut gewählte Namen sind beispielsweise checknumber(), getnoforders() oder writesum(). Eine Funktion soll eine, und nur eine klar definierte Aufgabe durchführen. Das Interface der Funktion ist selbsterklärend und beschreibt die Bedeutung der einzelnen Parameter. Ein Beispiel für eine entsprechend gestaltete Schnittstelle ist calculateprims(int from, int to) oder checkuserstate(string username, String password). Sven Müller, Thomas Hornberger 8.12.2005 Seite 6 von 26
2.5 Datenorganisation Es ist besser zusätzliche Variablen zu verwenden und auf die maximal mögliche Wiederverwendung zu verzichten, wenn dadurch die Lesbarkeit des Codes erhöht wird. Bei der Verwendung von abstrakten Datentypen (ADT) ist darauf zu achten, dass dieser die gegebene Aufgabe effizient bewältigen kann, jedoch keine beziehungsweise so gering wie möglich darüber hinaus gehende Funktionalität besitzt. Insbesondere bei ADT ist auf eine gut lesbare Schnittstelle zu achten. 2.6 Layout Das Layout sollte an allen Stellen konsistent gehalten werden, dies betrifft beispielsweise die Form der Einrückungen. Darüber hinaus sollte es dem logischen Aufbau des Programms entsprechen, in diesem Zusammenhang ist insbesondere auf die Reihenfolge von Methoden und Blöcken wie der Deklaration von globalen Variablen oder Konstanten zu achten. 2.7 Kontrollstruktur Zusammengehörende Anweisungen werden gekapselt, um diese Blockbildung auch zum Ausdruck zu bringen. Der normale Programmablauf folgt dem if-zweig und nicht dem else-zweig. Die verwendeten Kontrollstrukturen sind hinsichtlich ihrer Komplexität gerade so groß dimensioniert, als dies zur Erfüllung ihrer Aufgabe erforderlich ist. Auch die Verschachtelung sollte auf das minimal mögliche Maß reduziert werden. Abfragen unter Verwendung von booleschen Konstrukten sollten so einfach wie möglich zu halten sein, besondere Vorsicht ist bei der Anwendung des NOT-Operators geboten. Sven Müller, Thomas Hornberger 8.12.2005 Seite 7 von 26
3. Verschiedene 3.1 Einleitung Oft ist es nicht ausreichend seinen Quellcode in einer bestimmten Form zu schreiben. Je größer der Umfang eines Projektes, desto schwieriger wird es für andere, sich in diesen einzulesen. Um diesem Problem Abhilfe zu schaffen, gibt es eine Vielzahl von Werkzeugen, so genannte. Mit deren Hilfe ist es nicht nur möglich innerhalb des Quellcodes Kommentare zu generieren, sondern es lassen sich auch externe Dokumente erzeugen, in denen der Quellcode beschrieben wird. Auf den folgenden Seiten wird auf die bedeutendsten dieser eingegangen. 3.2 DOC++ DOC++ ist ein Dokumentationssystem für C, C++, IDL und Java, welches sowohl TeX- Ausgabe für sinnvolle Ausdrucke als auch HTML-Seiten für sinnvolle Online- Darstellungen der Dokumentation erzeugen kann. Die Dokumentation wird direkt den C/C++/IDL-Header- bzw. -Quelldateien oder den Java-Klassendateien entnommen. Beispiel einer mit DOC++ kommentierten c++ Klasse: /** Function to send information to the immediate uplink, to be gathered using \Ref{dm_gatherinfo}. @return 1 on error, 0 on success. int dm_sendinfo (const char * TAG, /// TAG to identify information const char * string /// The information string. ) Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 8 von 26
3.3 KDOC KDOC ist ein C++ Dokumentationswerkzeug, welches speziell für die Kommentierung von KDE-libraries ausgelegt ist. Es wurde entwickelt, da man mit DOC++ unzufrieden war. Die Syntax ähnelt Javadoc. KDOC extrahiert speziell formattierte Informationen über die Klassen aus den Header- Dateien und generiert HTML-Dateien, Latex oder man pages. Beispiel eines mit KDOC dokumentierten C++ Header-Dateien: // von KDOC ignorierter Kommentar /** * Dies ist meine Klasse. Die Klasse ist sehr einfach. * * @short Kurzbeschreibung der Klasse * @author Mein Name * @version 0.1alpha (string) class MyClass : public MyBaseClass { public: // ein leeres Doc-Tag. /** void mymethod(); // eine Methode mit mehr Information /** * Ich bin eine dokumentierte Methode. Sven Müller, Thomas Hornberger 8.12.2005 Seite 9 von 26
}; * * Hier steht noch mehr Information über die Methode. * * @see anotherclass#someothermethod * @see athirdclass * * @return wert ist Integer * @param para parameter * @param parb parameter. int mycutemethod( int para, const char *parb ); Sven Müller, Thomas Hornberger 8.12.2005 Seite 10 von 26
3.4 Ccdoc ccdoc ist ein kommandozeilen-orientiertes, einfach zu bedienendes Werkzeug um HTML-Dokumentationen aus C/C++ Header-Dateien zu generieren, also eine Art javadoc für C/C++ Entwickler. ccdoc wurde von Joe Linoff entwickelt und auf unterschiedliche Plattformen portiert. Der Quellcode wurde sogar öffentlich gemacht. So konnte (und kann) ccdoc von anderen Leuten auch auf weitere Plattformen portiert werden. Beispiel: // ================================================ //@{ // This is the brief description of the simple function. // // The simple function takes in two integer arguments, adds them together // and then returns the result. // @param x The y value. // @param y The x value. // @returns The sum of x and y. //@} // ================================================ extern "C" unsigned simple(unsigned x,unsigned y); Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 11 von 26
3.5 PERCEPS PERCEPS erzeugt aus C/C++-Header-Dateien eine Dokumentation in HTML. Das Ausgabeformat kann aber angepasst werden. PERCEPS ist ein Perlä-Skript, welches die C/C++ Header-Dateien parsed. Mithilfe von Templates passt es seine Ausgabe nach Wunsch an. Die Formate TeX, RTF, man page und Plain Text sind auch möglich. Beispiel: //! author="hannes" // Wird nicht interpretiert. //: Eine Beispiel-Klasse // Hier steht die detaillierte Beschreibung der Klasse. class Base { // Weitere Klassenbeschreibung // <I><B><FONT COLOR="red">HTML Code!</FONT></B></I> //!italic: Benutzerdefinierter Typ int private1; public : Base(int arg1); //: Konstruktor int public1(); //: eine öffentliche Objekt-Methode // Hier steht eine detaillierte Beschreibung der Funktion. // /* Dieser Kommentar wird ignoriert float public2( float arg1, float arg2 ); //: Weitere Methode //!param: arg1 Beschreibung von arg1 //!param: arg2 Beschreibung von arg2 class NestedClass { //: Eine innere Klasse public: int nestedvar1; float nestedvar2; float nestedmember2( float arg1, float arg2 ); }; protected : }; float protected1; //: Geschützte Objekt-Variable Sven Müller, Thomas Hornberger 8.12.2005 Seite 12 von 26
Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 13 von 26
3.6 JavaDoc JavaDoc ist ein Software-Dokumentationswerkzeug, das aus Java-Quelltexten automatisch HTML-Dokumentationsdateien erstellt. Für zusätzliche Informationen können spezielle Kommentare im Quelltext eingefügt werden. Kommentare können dabei für Interfaces, Klassen, Methoden und Felder über spezielle Doclet-Tags definiert werden. JavaDoc wurde ebenso wie Java von Sun Microsystems entwickelt und ist Bestandteil des Java 2 Software Development Kits (J2SDK). Als Doclet bezeichnet man in Anlehnung zu Applets Module, die von n zur Verarbeitung und automatischen Erzeugung von Dokumentation und eventuell auch Code eingesetzt werden. Das in JavaDoc integrierte Standard-Doclet erzeugt aus Java-Quelltexten eine API- Dokumentation in HTML. Es existieren zahlreiche alternative Doclets, um die API- Dokumentation in anderen Formaten, z.b. dem Windows Help Format, Framemaker / MIF, XML oder PDF zu erzeugen. Derzeit erfreuen sich noch Doclets zur Erzeugung von Code großer Beliebtheit, auch wenn sie mittelfristig wohl durch die in Java 1.5 hinzugefügten Annotationen abgelöst werden. Die neuen Annotationen in Java 1.5 werden vom Compiler nicht mehr ignoriert und sind somit auch im.class-file enthalten. Mit Hilfe des neuen Paketes java.lang.annotations können diese Informationen verarbeitet werden. public class Parent { @Deprecated public void foo(int x) { System.out.println("This method is deprecated and should not be used.");}} Sven Müller, Thomas Hornberger 8.12.2005 Seite 14 von 26
Beispiel: /** * Diese Klasse soll die Verwendung von Feldern bei Methodenaufrufen * demonstrieren. Insbesondere wird das Konzept des CALL BY REFERENCE gezeigt. * * @author bisanz * @version 1.0 public abstract class CTest { /** * Dieses ist unsere Feldgröße. Alle unsere Felder in dieser Klasse * sollen genau so groß sein. private static int ARRAY_SIZE = 3; /** * Die Startroutine des Programms. * * @param args Kommandozeilenparameter. Sie werden hier nicht verwendet. public static void main (String[] args) { int[] meinfeld = { 17, 23, -2 }; System.out.println("meinFeld:"); printarray(meinfeld); twice(meinfeld); System.out.println("meinFeld:"); printarray(meinfeld); int[] nocheinfeld = twicecopy(meinfeld); System.out.println("meinFeld:"); printarray(meinfeld); System.out.println("nochEinFeld:"); printarray(nocheinfeld); }} Sven Müller, Thomas Hornberger 8.12.2005 Seite 15 von 26
Beispielausgabe javadoc: Sven Müller, Thomas Hornberger 8.12.2005 Seite 16 von 26
3.7 Doxygen Doxygen ist ein Software-Dokumentationswerkzeug, das aus Quelltexten verschiedener Programmiersprachen automatisch eine Dokumentation erstellt. Doxygen wird seit 1997 als Dokumentationswerkzeug für C und C++ Quelltexte entwickelt. Gedacht war es für die Dokumentation großer Softwareprojekte. Dazu müssen speziell gekennzeichnete Kommentare in den Quelltext eingefügt werden. Doxygen unterstützt heute die Programmiersprachen C++, C, Java, Objective-C, IDL, PHP, C#, D und Actionscript. Die Dokumentation kann in den Formaten HTML, RTF, PostScript, PDF, Latex und als Man pages erzeugt werden. Das Ausgabeformat XML befindet sich zurzeit noch im Entwicklungsstadium. Von den Ausgabeformaten werden nur HTML, Latex und PDF weiter betrachtet, da die anderen Formate keine Formeldarstellung (man, RTF) erlauben. Die prinzipielle Vorgehensweise für jedes Projekt, was zukünftig mit Doxygen bearbeitet werden, soll ist immer gleich: Konfiguration für das konkrete Projekt erstellen Dokumentieren des Quelltextes während der Entwicklung Die Reihenfolge der Schritte spielt keine Rolle, da zu jedem Zeitpunkt eine neue Dokumentation eines Projektes (auch mit geänderter Konfiguration) möglich ist. Die initiale Konfigurationsdatei (Doxyfile) wird entweder über die Konsole oder über den Doxywizard erzeugt. DoxyWizard ist ein grafischer Aufsatz zur Erstellung und Bearbeitung von Doxygen-Konfigurationsdateien. Beispiel einer Konfigurationsdatei: # Doxyfile 1.3.7 #------------------------------------------------------------------------- # Project related configuration options #------------------------------------------------------------------------- PROJECT_NAME = XCTL32 PROJECT_NUMBER = OUTPUT_DIRECTORY = /u/ddamm/disk/doxygen/doxygenbeispiel/ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = German... JAVADOC_AUTOBRIEF = YES... #------------------------------------------------------------------------- # Build related configuration options #------------------------------------------------------------------------- EXTRACT_ALL = NO... #------------------------------------------------------------------------- Sven Müller, Thomas Hornberger 8.12.2005 Seite 17 von 26
# configuration options related to the input files #------------------------------------------------------------------------- INPUT = /u/ddamm/disk/doxygen/doxygenbeispiel/ FILE_PATTERNS = RECURSIVE = YES EXCLUDE =... #------------------------------------------------------------------------- # configuration options related to the HTML output #------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION =.html HTML_HEADER = HTML_FOOTER =... #------------------------------------------------------------------------- # configuration options related to the LaTeX output #------------------------------------------------------------------------- GENERATE_LATEX = YES LATEX_OUTPUT = latex LATEX_CMD_NAME = latex... #------------------------------------------------------------------------- # Configuration::additions related to the search engine #------------------------------------------------------------------------- SEARCHENGINE = NO Zum zweiten Schritt ist unbedingt anzumerken, dass es sich durchaus lohnt, auch völlig unkommentierten Quelltext mit in ein (vorhandenes) Projekt aufzunehmen. Doxygen generiert dann zwar keine ausführlichen Informationen, aber die Dateien, Klassen und Funktionen werden zumindest mit in die Übersicht aufgenommen, und man kann sich einen groben, schnellen Überblick verschaffen. Die Arten der Dokumentation lehnen sich in den entsprechenden Sprachen den z.t. schon länger existierenden Werkzeugen an. Konkret bedeutet das, dass folgende Dokumentationsmöglichkeiten von Doxygen unterstützt werden: JavaDoc für Java-Quelltexte KDoc bzw. Qt-Stil für QT bzw. KDE-Projekte Zusätzlich existieren aber noch einige Erweiterungen, die weitergehende Dokumentationsmöglichkeiten bieten. Sehr positiv fällt z.b. auf, daß Informationen aus dem CVS über die entsprechenden Schlüsselworte ebenfalls extrahiert werden können. Ein Dokumentationsblock hat also eine der folgenden Formen: einzeilig: //! Eine Zeile Dokumentationstext im Qt-Stil. /// Eine Zeile Dokumentationstext im JavaDoc-Stil. Sven Müller, Thomas Hornberger 8.12.2005 Seite 18 von 26
mehrzeilig: /*! mehrzeiliger Dokumentationstext im Qt-Stil führende * in der Zeile werden entfernt; werden sie dort benötigt, müssen sie zweimal eingegeben werden /** * mehrzeiliger Dokumentationstext * im JavaDoc-Stil * führende * in der Zeile werden ebenfalls entfernt; * werden sie dort benötigt, müssen sie zweimal eingegeben werden Zusätzlich können nun, um aus diesem Kommentar auch einen geeigneten Dokumentationseintrag zu machen, einige besondere Tags angegeben werden, die die nachfolgende Klasse, Methode, Struktur oder auch gesamte Datei näher spezifizieren. Ein Tag wird durch \Tagname bzw. @Tagname im Kommentar gekennzeichnet. Die am häufigsten verwendeten Tags sind: @param beschreibt Parameter einer Funktion @return beschreibt Rückgabewerte einer Funktion @class gibt nachfolgender Klasse (aussagekräftigeren) Namen @file gibt einen Überblick über den Inhalt einer Datei @struct beschreibt die Struktur näher @brief Kurzbeschreibung des nachfolgenden Elements (Klasse, Funktion, usw.) @author Autor (Hier kann sinnvollerweise auch nur $Author$ bzw. $Author:hame$ stehen) @version Versionsnummer @date Datum @bug Bekannte Fehler @warning Warnungen und Hinweise @see Referenzen auf andere Dokumente und Quelltexte @todo Was ist noch zu machen @mainpage <titel> Beschreibung der Hauptseite der Dokumentation @section <name> <titel> Beginnt ein Kapitel @li <listenelement> Erzeugen einer Liste Sven Müller, Thomas Hornberger 8.12.2005 Seite 19 von 26
Dies ist nur eine Auswahl. Es werden auch eine Vielzahl von HTML-Befehlen und auch Latex-Befehlen (für das Einbinden von Formeln) unterstützt. Die Konfiguration in der Datei Doxyfile unterteilt sich in einen allgemeinen Teil für Projektname, Versionsnummer, Projektverzeichnis, Dateien, Ebenen der Dokumentation, usw. und einen Teil speziell für das entsprechende Ausgabeformat. Es ist zu beachten, dass jedes Projekt eine eigene Konfigurationsdatei benötigt. Für die Konfigurationsdatei sollte man eine Vorlage anlegen: einheitliche CSS-Seitengenerierung (HTML) einheitliche Sprache (Englisch ist zu bevorzugen, da einige Einträge nur unzureichend oder gar nicht übersetzt sind) einheitliche Struktur/Tiefe der Dokumentation Einbindung der mathematischen Formeln bei komplexen Algorithmen Erstellen von Vorlagen für die entsprechenden Ausgabeformate erfolgt duch doxygen -w <typ> <optionen> Dabei kann <typ> "rtf", "html" oder "latex" sein. Die Optionen hängen vom Typ und von der Konfigurationsdatei ab. Anhand der Beispieldateien soll abschließend die Verwendung der Tags und eine vollständige Dokumentationsproduktion mit doxygen demonstriert werden. Sven Müller, Thomas Hornberger 8.12.2005 Seite 20 von 26
Beispiel-Klasse: /** Klasse realisiert Beispiel2. * * @author Hannes * @date 19.10.2005 * * @version 0.2 KAPITEL 4. DOKUMENTATION 11 Abbildung 4.2: Klassenbeschreibung mit Doxygen * Toten Code entfernt. * * @version 0.1 * Kommentare hinzugefügt (Doxygen). class Beispiel2 {} Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 21 von 26
Beispiel-Klasse: /** Klasse realisiert Beispiel3. * * @author Hannes * @date 19.10.2005 class Beispiel3 { public: /** Addiert zwei ganze Zahlen. * @param[in] a Die erste Zahl. * @param[in] b Die zweite Zahl. * @return Die Summe der beiden Zahlen a und b. * @see Addiere(double,double) int Addiere(int a, int b); double Addiere(double a, double b); } Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 22 von 26
Beispiel-Klasse: /** Darstellung von Listen. * * Einfache Listen: * @li Liste 1a KAPITEL 4. DOKUMENTATION 16 Abbildung 4.6: Erstellung von Listen mit Doxygen * @li Liste 1b * * @li Liste 2a * @li Liste 2b * * Verschachtelte Listen: * <ul> * <li>liste 3a</li> * <ol> * <li>liste 3a.1</li> * <li>liste 3a.2</li> * </ol> * <li>liste 3b</li> * </ul> class Beispiel4 {} Beispielausgabe: Sven Müller, Thomas Hornberger 8.12.2005 Seite 23 von 26
Beispiel für Formel-Anwendung: /** * Der Abstand zwischen \f$(x_1,y_1)\f$ und \f$(x_2,y_2)\f$ ist * \f[\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}.\f] Beispielausgabe: Der Abstand zwischen (x1;y1) und (x2;y2) ist Hinweis: Dieses funktioniert aber nur für die HTML- oder LATEX-Ausgabe. Sven Müller, Thomas Hornberger 8.12.2005 Seite 24 von 26
Beispiel aus dem Open-Source Projekt Mozilla, wo mit Doxygen gearbeitet wird: Die vorangegangenen Beispiele demonstrieren die Fähigkeiten und Möglichkeiten von Doxygen. Mit Doxygen ist es mit relativ wenig Aufwand möglich, Quelltexte so zu dokumentieren, dass sie für andere Entwickler nutzbar sind. Gegen das Konzept von Doxygen, die Dokumentation und die Implementierung eines Programmes in den selben Quelltext zu speichern, spricht eigentlich nur, dass die Quelltexte schnell unübersichtlich werden, wenn die Dokumentation sehr umfangreich ausfällt. Sven Müller, Thomas Hornberger 8.12.2005 Seite 25 von 26
4. Fazit Im Laufe der Entwicklung von Programmiersprachen und Software nahm insbesondere die Bedeutung von guten Quellcode-Kommentaren zu. Mit dem Aufkommen der objektorientierten Programmierung wurden auch die Dokumentationen immer umfangreicher, da sich große Projekte nur so über Jahre sinnvoll entwickeln lassen. Um Code sinnvoll und einheitlich zu kommentieren entstanden viele Werkzeuge, die diese Arbeit unterstützen sollen. Ein großer Nachteil erster solcher Werkzeuge wie KDOC, DOC++ oder Cocoon ist, dass sie lediglich für C++ Programme ausgelegt sind. Weiterhin haben sie eigene Anforderungen zur Formatierung an den Quelltext. Suns Javadoc revolutionierte sozusagen die und setzte neue Standards, an denen sich nun alle Konkurrenten orientieren. Doxygen hingegen hebt sich durch seine Anzahl an unterstützten Sprachen hervor. Ein weiterer Vorteil ist die Kompatibilität zu Javadoc und KDOC. Letztlich hat man noch die Wahl aus einer Vielzahl an unterstützten Ausgabeformaten. Doxygen ist durch seine Großzahl an Funktionen, sowie Variabilität in seinen Formatierungen ein den heutigen Ansprüchen gerecht werdendes und mittlerweile auch etabliertes Dokumentationswerkzeug. Einziger zu erwähnender Nachteil ist die lange Einarbeitungszeit bei Doxygen, aufgrund seines Umfangs. Literaturverzeichnis [GG00] Grünwied, G.; Kontakt & Studium Bd.668 - Software-Dokumentation, Expert-Verlag [AH03] Hunt, A.; Der Pragmatische Programmierer, 2003 [FP05] Padberg, F.; Vorlesungsskript Softwaretechnik2, Richtlinien für guten Programmierstil, Sommersemester 2005, TU Clausthal [AZ04] Zeller, A.; Vorlesungsskript Software-Dokumentation, Lehrstuhl für Softwaretechnik, Universität des Saarlandes, Saarbrücken 2004 Internet-Referenzen [Doxygen Homepage] (http://www.doxygen.org) [DOC++ Homepage] (http://www.zib.de/visual/software/doc++/index.html) [KDOC Homepage] (http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/) [Ccdoc Homepage] (http://www.joelinoff.com/ccdoc/) [Perceps Homepage] (http://starship.python.net/crew/tbryan/perceps/) [Trolltech] (insbesondere Qt-Bibliotheken) (http://www.trolltech.com) [Mozilla Homepage] (http://www.mozilla.org) [Sun JavaDoc] (http://java.sun.com/j2se/javadoc/index.html) [AT&T Graphviz] (http://www.research.att.com/sw/tools/graphviz/) [Wikipedia] (http://www.wikipedia.de) [Google] (http://www.google.de) Sven Müller, Thomas Hornberger 8.12.2005 Seite 26 von 26