Inhaltsverzeichnis

Startseite

Einleitung

Dokumentation für den Endanwender

System-Dokumentation

Projektdokumentation mit SoDoM

Zusammenfassung

Literaturverzeichnis

Online-Folien

Kapitel 2 - System-Dokumentation

• Motivation

• Literate Programming

• Werkzeuge zur System-Dokumentation

• Rational Rose & SoDA

• Automatisch generierte HTML-Dokumentation mit Javadoc

• Entwicklungsbegleitende Dokumentation mit dem Inprise JBuilder

• Warum ist dies wichtig?

Motivation

Die Wartung von Software nimmt einen immer höheren Stellenwert im Lebenszyklus von Softwaresystemen dar. Dies veranschaulicht auch die Grafik.

entnommen aus [Boehm82]

Dieser Trend wird noch verstärkt durch objektorientierte Methoden der Softwareentwicklung, da mittels Wiederverwendung eine immer kürzer werdende Entwicklungszeit erreicht werden kann. Dies bedeutet aber auch, daß Entwicklung und Wartung von Softwaresystemen immer mehr miteinander verschmelzen.

Die Frage:

Wie lassen sich Softwaresysteme durch gute Dokumentation wartbar und wiederverwendbar gestalten?

läßt sich mit Methoden der System-Dokumentation lösen. Dieses Kapitel stellt Ansätze und Werkzeuge vor, die eine derartige und durchgängige System-Dokumentation unterstützen.

2.1 Literate Programming

"Programs are written to be executed by computers rather than to be read by humans. Ideally, it should be the other way round. When writing programs, we should not try to instruct the computer what to do, but rather we should try to tell humans what we want the computer to do" [Knuth92]

Dieses Zitat von Donald E. Knuth bringt die Idee des Literate Programming zum Ausdruck. Der Ansatz des Literate Programming ist, Programme genauso lesbar wie gewöhnliche Literatur zu gestalten. Hauptziel ist es dabei nicht, ein ausführbares Programm zu erhalten, sondern eine dem Problem und dem Kontext angepaßte Lösung zu dokumentieren. Dies weist Ähnlichkeit mit der Definition eines (Entwurfs-)Musters auf. [Definition eines Musters] Mit der Idee des Literate Programming entwickelte Knuth ebenfalls das WEB System, welches diesen Ansatz unterstützt. WEB Programme bestehen aus einer Serie von Dokumentationsblöcken, die sowohl den Dokumentationstext als auch den Sourcecode enthalten. Jeder Abschnitt behandelt dabei einen bestimmten Teil des Gesamtsystemes und hat Verzweigungen zu anderen damit in Beziehung stehenden Abschnitten. Für die Compilierung wird der Sourcecode automatisch aus diesen Abschnitten extrahiert.

Das WEB System wurde für viele Programmiersprachen entwickelt. Darunter für Pascal, C, Modula-2, Lisp und Fortran, aber auch für objektorientierte Sprachen wie C++ und Smalltalk. Der Vorteil liegt in dem positiven Einfluß den eine sofortige Dokumentation des Sourcecodes auf die Korrektheit, Konsistenz und Vollständigkeit der Dokumentation hat.

3. Here is an outline of the entire Pascal program:

program sample:
var [Global variables 4]
[Random number generation procedure 5]
begin [The main program 6]
end

4. The Global variables M and N have already been mentioned; we had better declared them. Other global variables will be declared later.

define M_max=5000 {max. value of M}

[Global variables 4]
M: integer; {size of the sample}
N: integer; {size of the population}

See also Sections 7, 9, and 13.
This code is used in Section 3.

[Knuth84]

Leider hat sich Literate Programming nicht durchsetzen können. Doch was sind die Nachteile? Dieses System funktioniert dann hervorragend, wenn während der Entwicklung schon sofort dokumentiert wird. Dies ist jedoch erst dann möglich, wenn die genaue Spezifikation vorliegt, bzw. keine Veränderungen mehr vorzusehen sind. In der Realität steht die Struktur eines Systems in der Regel nicht von Anfang an fest. Vielmehr gibt es mehrere Versuche und Veränderungen. Dieses Szenario kennzeichnet viele Softwareprojekte. Oft muß auf neue und veränderte Kundenanforderungen eingegangen werden. Die Dokumentation muß flexibel werden. Dazu ist wiederum Hypertext ein geeignetes Mittel.

2.2 Werkzeuge zur System-Dokumentation

Um die System-Dokumentation zu unterstützen und zu motivieren sind verschiedene Werkzeuge auf dem Markt verfügbar. Ich möchte hier nur kurz auf einige wenige eingehen.

2.2.1 Rational Rose & SoDA

Ein Werkzeug, welches leider nur recht schlechte Unterstützung für die Dokumentation bietet, ist Rational Rose von Rational Corporation. Es erlaubt leider nur kleine Notizen, die bei der Analyse und dem Design von Softwaresystemen an diverse Diagramme wie Use-Case oder Klassendiagrammen eingetragen werden können. Ich gehe deshalb auf Rational Rose ein, weil es einerseits die Anwendung von Entwurfsmustern (hoffentlich bald) untersützen wird, andererseits weil die unter Rational Rose modellierten Use-Case und Klassendiagramme mittels des Dokumentationswerkzeuges "SoDA" aus dem Hause Rational in ein automatisch generiertes und konfigurierbares WORD-Dokument umgesetzt werden können. Dazu werden die Notizen, die bei der Modellierung beispielsweise einer Klasse gemacht wurden, in die Dokumentation dieser Klasse in dem WORD-Dokument übernommen.

Bei Rational Rose handelt es sich um ein Werkzeug zur "Visualisierung" von Analyse- und Design Entscheidungen. Die Use-Case Diagramme helfen dabei, ein Softwaresystem in einer bestimmten einheitlichen Notationsform, heute meistens die UML (Unified Modeling Language), zu modellieren. Ein weiteres Feature von Rational Rose ist die Unterstützung des Roundtrip-Engineerings. Dies macht es möglich sowohl Veränderungen in einem Diagramm direkt in eine Zielsprache zu übertragen, als auch (rückwärts) Veränderungen im Sourcecode in die Diagramme übertragen zu lassen. SoDA hingegen, ist ein Add-On für Microsoft Word, welches aus den Dateien, die mit Rational Rose erstellt wurden, entsprechende Dokumentationen unter Microsoft Word automatisch generieren kann.

Die unten stehenden Screenshots zeigen ein Use-Case Diagramm von Rational Rose(links), ein Klassendiagramm in UML-Notation von Rational Rose (mitte), sowie ein automatisch generiertes WORD-Dokument unter SoDA (rechts).

Wie man in dem Screenshot von SoDA sehen kann, werden die Dokumentationen sämtlicher Attribute einer Klasse automatisch angelegt. Allerdings ist auf dieser Ebene ein Roundtrip-Engineering nicht möglich. Änderungen unter SoDA werden also nicht in die Dokumentation in den Diagrammen übernommen.

2.2.2 Automatisch generierte HTML-Dokumentation mit Javadoc

Im Java Development Kit von Sun Microsystems sind außer dem Java Compiler javac auch weitere andere Werkzeuge enthalten. So gibt es zusätzlich noch einen Appletviewer und auch ein Dokumentationswerkzeug namens Javadoc. Die Benutzung erfolgt ähnlich wie bei einem Compiler. Die zu dokumentierende .java Datei wird javadoc übergeben und es wird automatisch eine HTML-Beschreibung der enthaltenen Klassen generiert. Wie solch eine HTML-Datei aussieht, kann man sich [hier] ansehen.

Es können jedoch lediglich die mit public gekennzeichneten Klassen auf diese Weise dokumentiert werden. Die von javadoc generierten Klassendokumentationsdateien beschreiben die Klasse(oder das Interface) sowie ihre Vererbungshierarchie. Außerdem wird jedes public- und protected Element der Klasse indexiert und beschrieben. Die generierte Datei enthält auch alle "DOC"-Kommentare die mit der Klasse und ihren Methoden, Konstruktoren und Variablen verknüpft sind. Ein "DOC"-Kommentar bzw. Dokumentationskommentar ist ein Java-Kommentar, der mit /** beginnt und mit */ endet. Ein solche Doc-Kommentar kann auch HTML-Tags enthalten (obwohl er keine Strukturtags wie h1 oder hr enthalten sollte).

2.2.3 Entwicklungsbegleitende Dokumentation mit dem Inprise JBuilder

Mit dem Inprise JBuilder ist eine Entwicklungsumgebung entwickelt worden, die eine System-Dokumentation von Anfang an unterstützt. Obwohl es sich bei dem JBuilder mehr um ein Werkzeug zur Implementierung handelt, können auch frühe Entwurfsentscheidungen sofort dokumentiert werden. So wird beim Anlegen eines neuen Projektes automatisch ein HTML-Dokument angelegt, welches die noch zu erledigenden Aufgaben erfaßt. Siehe dazu Bild 1.

Bild 1

Es kann zunächst eine Beschreibung der Softwarekomponente eingetragen werden. Die Dokumentation der einzelnen Klassen geschieht ähnlich wie bei Rational Rose in Notizform am linken unteren Bildschirmrand. Diese Notizen werden dann beim Compilieren in den Quelltext als Kommentare eingesetzt. Bild 2 zeigt dazu ein Beispiel.

Bild 2

Diese Art der Dokumentation ist natürlich nur sehr unvollständig. Sie beschreibt lediglich den Zweck einer Softwarekomponente und hilft bei der Planung ihrer Erstellung. Die beschreibende HTML-Seite wird zwar automatisch generiert, der Anwender wird allerdings nicht explizit aufgefordert, diese auch zu editieren. Oft wird dies auch einfach "vergessen". Es dient eher einer kurzfristigen Projektplanung, damit nichts vergessen wird.
Die Kommentare im Sourcecode sind zwar recht hilfreich, sollten jedoch nur eine Ergänzung zu einer umfassenderen Dokumentation des Entwicklungsprozesses darstellen. Oft wird hierbei nur der grobe Zweck notiert, nicht aber, welche Anforderungen diese und keine andere Implementierung notwendig machten. Dies ist Aufgabe einer vollständigen Softwaredokumentation.

2.3 Warum ist dies wichtig?

Das ganze Verfahren der Softwaredokumentation ist zunächst sehr zeitaufwendig. Man mag denken, die Zeit wäre besser investiert, wenn man diese Zeit für die Programmentwicklung bzw. Design und Implementierung nutzen würde. Schließlich sind Fehler, die in der Analyse und Design Phase begangen werden, sehr sehr teuer. Jedoch kann auch hier die Dokumentation Abhilfe schaffen. Es empfiehlt sich sogar, mißlungene Entwicklungen samt der Fehler, die dazu führten zu dokumentieren und aufzubewahren. Damit kann eine Wiederholung dieser Fehler vermieden werden.

In den Kapiteln 1 und 2 wurden bereits 2 wichtige Teilgebiete der Softwaredokumentation behandelt. Wünschenswert wäre allerdings eine durchgängige Dokumentation, wenn möglich auf einer höheren Ebene, die von der Analyse und Design-Phase, über die Implementierung bis hin zur Anwendung(Tutorien siehe Kapitel 1) und Wartung eine durchgängige, also lückenlose, und somit vollständige Dokumentation. Damit wird der Entwicklungsprozeß eines Softwaresystemes auch für andere nachvollziehbar und reproduzierbar.

Angesichts der Zertifizierung der DIN-ISO 9001 zur Qualitätssicherung ist solch eine Dokumentation zwingend erforderlich. Gerade in Bereichen wie bespielsweise der Raumfahrttechnik oder im Straßen- und Luftverkehr ist es mitunter lebenswichtig, daß die eingesetzten Softwaresysteme einwandfrei ihren Dienst verrichten. Ansonsten könnten Menschenleben gefärhdet sein, oder große finanzielle Verluste, zum Beispiel durch den Ausfall eines Satelliten, wie erst kürzlich geschehen, entstehen.
Diese schreckliche Erfahrung mußte beispielsweise bei der Challenger-Katastrophe gemacht werden.

Ein Hilfsmittel zur Qualitätssicherung bietet hier die Projektdokumentation, die nahezu alle Elemente verbindet und eine übergeordnete Dokumentation des Softwaresystemes darstellt.

Dieses wird nun in Kapitel 3 - Projektdokumentation behandelt.