Oft wird die Dokumentation eines Softwareprogrammes als notwendiges Übel betrachtet - scheint es doch zunächst wichtiger, das System fertigzustellen, als Berge von bedrucktem Papier zu produzieren. Michael Abel* versucht in seinem Beitrag, Bedeutung und Möglichkeiten der Systemdokumentation aufzuzeigen und die Einsatzmöglichkeiten in der täglichen Praxis des Entwicklers hervorzuheben.
Die Frage, was Dokumentation eigentlich bedeutet, läßt sich nur schwer mit einem einzigen Satz beantworten. Hinter diesem Terminus verbirgt sich eine Reihe von Gesichtspunkten. Ein zunächst einfacher Weg, den Begriff zu definieren und seine Bedeutung darzulegen, ist die Formel: Softwareprodukt = Code plus Dokumentation. Eine Dokumentation ist also zu allererst ein Qualitätsmerkmal der Software. Insbesondere bei einer späteren Änderung des Produktes, beispielsweise bei der Korrektur von Fehlern, der Erweiterung von Funktionen oder der Anpassung an sich verändernde Umgebungen besteht die Notwendigkeit, zu wissen, wie das Programm konzipiert wurde.
Programmcode verständlicher gestalten
Wer schon einmal ein fremdes oder selbstgeschriebenes, aber älteres Programm durchlesen, Verstehen oder ändern mußte, weiß, wie sehr auch nur die geringste Zusatzinformation bei dieser Aufgabe helfen kann. Die Dokumentation erfüllt zunächst die Aufgabe, den eigentlichen Programmcode verständlicher zu gestalten, und ist somit ein wichtiger Aspekt für den Entwickler, um die Flexibilität seines Produktes zu verbessern.
Bei der Einteilung der verschiedenen Dokumentationsarten kann man grundsätzlich zwischen vier Versionen unterscheiden. Die Abbildung auf Seite 90 gibt einen Überblick über diese unterschiedlichen Dokumentationsformen und deren Zielgruppen. Die erste Gruppe umfaßt die externe Dokumentationsformen, also Fälle, in denen die Dokumentation getrennt vom eigentliche Softwareprodukt vorliegt. Einer der wichtigsten Vertreter dieser Gruppe ist das Pflichtenheft. Es stellt das Ergebnis der Systemanalyse dar, in der der Entwickler versucht, festzustellen, welche Anforderungen das zukünftige System zu erfüllen hat.
Gleichzeitig ist das Pflichtenheft Teil des Vertrags zwischen Auftraggeber und Entwickler. Die Abnahme des Pflichtenheftes durch den Auftraggeber sichert den Entwickler ab; nachträglich kann nicht mehr verlangt werden, als im Pflichtenheft definiert wurde. Auf der anderen Seite muß das fertige System alle hier festgelegte Funktionen enthalten, ansonsten kann der Auftraggeber auf einer Nachbesserung bestehen.
Ein weiteres oft verbreitetes Dokument, das man dieser Gruppe zuordnen kann, ist das Benutzerhandbuch, das dem Anwender den Umgang mit dem System erleichtern soll. Angesprochen auf mangelhafte oder fehlende Benutzerdokumentation, erklären zwar viele Entwickler, daß ihr System benutzerfreundlich sei und daher Handbücher sich erübrigten. Ein durchschnittlicher Anwender wird auch eine Vielzahl seiner täglichen Aufgaben ohne einen Blick in die Handbücher erledigen können - was aber in den berühmten Ausnahmefällen?
Wie umfangreich die Benutzerdokumentation zu einem System erstellt wird, scheint daher weniger von der Komplexität des Produktes abzuhängen als von der Bedeutung, die der Entwickler diesem Teil der Anwendung zumißt. So variiert nicht nur die Dicke der Handbücher, sondern auch der Auswahl. Neben reinen Nachschlagewerken für erfahrene Benutzer (Reference Manuals) existieren Anleitungen zur Installation, zur Einführung in die Anwendung (Useres Guide) bis hin zur "Technical Reference", bei der die internen Strukturen des Produktes im Mittelpunkt stehen.
Aus Sicht des Programmierers kommt der Funktionsdokumentation entscheidende Bedeutung zu. Sie stellt das Gegenstück zum Pflichtenheft dar und beschreibt, wie die vorgegebenen Aufgaben gelöst wurden und das System arbeitet. Deshalb ist sie unentbehrlich für Tests, Änderungen, Portierungen und den Anschluß an andere Systeme. Da sich allerdings die Zielsetzung dieses Schriftstücks mit denen der integrierten Dokumentation überschneidet, ist Vorsicht geboten. So macht es sicherlich wenig Sinn, im Rahmen der Funktionsdokumentation den Sourcecode in voller Länge auszudrucken. Vielmehr sollte der Ablauf eines Programms durch geeignete Schaubilder (zum Beispiel Nassi-Shneidermann oder PAP) dargelegt werden.
Ein weiterer Vertreter der externen Dokumentation ist die Wartungsdokumentation. Sie dient dazu, alle Änderungen, die an einem Produkt vorgenommen werden, aufzuzeichnen. So gesehen stellt sie eine Ergänzung zur Funktionsdokumentation dar, die das System nach der Entwicklung beschreibt. Hier finden Korrekturen, Ergänzungen und Erweiterungen ihren Platz. Bleiben noch die Schulungsunterlagen als letztes Beispiel für eine externe Dokumentation. Im Gegensatz zur Benutzerdokumentation sollen diese nicht auf konkrete Befehle eingehen, sondern größere Zusammenhänge vermitteln, praktische Einsatzbeispiele geben und den Schulungsteilnehmern beim Lernen helfen.
Der externen steht die integrierte Dokumentation gegenüber, die im eigentlichen Code des Programms enthalten ist. Unter dieser Dokumentationsart versteht man vor allem auch die Möglichkeit zu Kommentaren, um die codierten Anweisungen verständlicher zu machen. Leider wird diese Form der Dokumentation oft mißbraucht, wie das Beispiel a:= a + 1; a wird um 1 erhöht zeigt. Kommentare dieser Art sind ärgerlich, weil sie dem Leser des Programmcodes keine zusätzliche Information vermitteln, sondern nur den Umfang des Programmes unnötig aufblähen.
Die durch die Sprachen gebotenen Möglichkeiten, den Programmcode zu strukturieren, dürfen als Dokumentationsansatz ebenfalls nicht vergessen werden. Durch den übersichtlichen Aufbau eines Moduls gewinnt jedes Programm an Lesbarkeit. Daher sollten Deklarationen von Anweisungen getrennt und der Ablauf durch Einrückungen und Leerzeilen verdeutlicht werden. Die meisten modernen Programmiersprachen bieten hierzu bereits geeignete Möglichkeiten.
Eines der Hilfsmittel der integrierten Dokumentation ist die möglichst eindeutige Wahl von Bezeichnern. Variable, Unterprogramme, Sprungmarken und weitere Elemente eines Programmes werden durch Bezeichner mit Namen versehen. Diese können dann in der Regel in vorgegebenen Grenzen frei gewählt werden. Durch die Verwendung von sprechenden Variablen und anderen eindeutigen Bezeichnern wird die Logik eines Moduls schneller erfaßbar. Statt i, x und a sollten deshalb Begriffe wie Anzahl, Datensätze, Fehlercode oder ähnliche Termini zum Einsatz kommen.
Ein weiterer Ansatz, ein System zu dokumentieren, ist die sogenannte Selbstidentifikation. Ziel dieser Dokumentationsweise ist es, bei jeder Version deutlich zu machen, von welchem Programm sie stammt. Bedeutung erlangt dieses Vorgehen vor allem bei Multiuser-Systemen. Jeder Ausdruck sollte hier, beispielsweise auf einer Kundenliste, auf dem Titelblatt und gegebenenfalls auch auf allen folgenden Blättern Informationen wie Name des Programms, Version, Datum, Uhrzeit und eventuell auch den Namen des Benutzers enthalten.
Auch Daten, die auf Speichermedien wie Festplatten abgelegt werden, lassen sich im Rahmen der Selbstidentifikation kennzeichnen. Oft geschieht dies durch Vergabe eines geeigneten Namens für die Datei, wobei die Extension angibt, zu welchem Programm diese Datei gehört. Eine weitere Möglichkeit besteht darin, die Datensätze einer Datei um ein Feld zu erweitern, welches die Satzart aufnimmt. Diese fünf Zeichen umfassende Markierung ermöglicht es, jeden einzelnen Satz einem bestimmten Anwendungssystem zuzuordnen und entsprechend zu kennzeichnen.
Letzter Punkt in der Liste der verschiedenen Dokumentationsweisen ist die funktionale Dokumentation. Hinter diesem Begriff verbergen sich alle aktiven Funktionen eines Computersystems. Dazu zählen Hilfesysteme und Lernprogramme, aber auch Online-Manuals, die Informationen, die normalerweise in Handbüchern zu finden sind, auf dem Bildschirm ausgeben (beispielsweise das "man"-Kommando in Unix-Systemen). Die Vorzüge dieser Dokumentationsart sind deren schnelle Verfügbarkeit: Ein Druck auf die Hilfe-Taste liefert die gewünschten Ergebnisse oft schneller als die Suche in dem entsprechenden Handbuch.
Der hier vorgestellte Überblick über die verschiedenen Dokumentationsarten ist keineswegs vollständig. Dennoch sollte er verdeutlichen, daß sich Systementwickler zunächst Gedanken darüber machen müssen, welche dieser Möglichkeiten sie nutzen wollen. Abschließend werden nun einige Lösungen für die Praxis vorgestellt, die mit relativ wenig Aufwand zu realisieren sind, gleichzeitig aber einen deutlich wahrnehmbaren Effekt auf die Systementwicklung und -wartung haben.
Einheitlichen Programmrahmen vorgeben
Da eine integrierte Dokumentation einfach, schnell und dadurch effektiv zu realisieren ist, verkörpert diese Form wohl den wichtigsten Vertreter aller Dokumentationsarten. Hinzu kommt der Vorteil, bei einer Änderung im Programmcode beinahe gleichzeitig auch die Kommentare entsprechend korrigieren zu können. Auch der Änderungseintrag im Kopf des Moduls ist schnell realisiert. Im Vergleich stellt sich die Verwaltung von Änderungen in externen Dokumenten um einiges aufwendiger dar, sie befinden sich deshalb meist nicht auf dem neuesten Stand.
Ein weiterer leicht zu realisierender Punkt ist die Vereinfachung der Programm-Erst- und Weiterentwicklung durch eine definierte Systematik. Dazu werden während des Systementwurfs Vorgaben für Bezeichner, beispielsweise Variablennamen oder Unterprogramm-Bezeichnungen festgelegt, was die Absprachen bei der Arbeit im Team wesentlich erleichtert. Zusätzlich sollte man einen einheitlichen Programmrahmen vorgeben, der zum Beispiel einen Kommentarkopf für wichtige Daten und einen vorstrukturierten Deklarations- und Anweisungsteil enthält.
Eine nicht zu unterschätzende Rolle spielt letztlich die Organisation. So kann die auf den ersten Blick unscheinbare Idee, sich vor der Realisierung eines Projektes über die Aufteilung von Daten und Programmen auf verschiedene Verzeichnisse Gedanken zu machen, bei der praktischen Arbeit erhebliche Vorteile bringen. Die strikte Trennung von Quell-Code, fertigen Modulen, Dokumentation, Testfällen und den vielen anderen Daten, die während einer Systementwicklung anfallen, erleichtert erfahrungsgemäß das Wiederfinden von Informationen erheblich. Hinter dem gleichen Stichwort verbirgt sich die Idee, die von dem zu entwickelnden System verwendeten Daten eindeutig zu verwalten. Die Möglichkeit, durch Einführung einer Satzart Dateien überprüfbar zu machen, wurde weiter oben bereits behandelt. Ein zusätzlicher Schritt in diese Richtung ist die Verwendung kommentierter Textdateien für Benutzereinstellungen, Profile oder wie die Bezeichnungen im einzelnen auch immer lauten mögen.
Diese Dateien, die erstmalig bei der Installation eröffnet werden, lassen sich entweder vom Anwender mit einem beliebigen Editor erstellen oder aber durch entsprechende Funktionen des Programms generieren. Dabei werden Informationen wie der Name des Programms, Version, Datum und Uhrzeit mitgespeichert. Ähnliches geschieht, wenn Programme Ausgaben im Postscript-Format erzeugen: Auch hier wird ein Vorspann mit den entsprechenden Informationen geliefert.
Wie die gesamte DV ist auch der Bereich der Dokumentation ständigen Veränderungen unterworfen. Wer zum Beispiel heute schon Generatoren einsetzt, um Teile seiner Anwendung zu entwerfen, muß natürlich auf eine andere Weise dokumentieren, als jemand, der jede Zeile von Hand codiert. Komplette Entwicklungssysteme oder Sprachen der vierten Generation nehmen dem Entwickler oft kleine Routineaufgaben ab und zeigen erste Schritte in die Richtung der automatischen Dokumentation.
Neben all diesen Betrachtungen sollte aber nicht vergessen werden, daß es Software-Qualitätsmerkmale gibt, die - abhängig vom jeweiligen System - noch wichtiger sind als eine gute Dokumentation, etwa Zuverlässigkeit oder die Benutzerfreundlichkeit der Anwendung. Das Prinzip der Dokumentation ist nur eine aus der Vielzahl der Software-Engineering-Methoden, die alle zusammen das Ziel verfolgen, die Qualität von Software zu erhöhen.