Die Notwendigkeit und Nützlichkeit einer guten Software-Dokumentation wird von niemandem bestritten. Dennoch: Gäbe es eine Abstimmung über die begehrtesten Tätigkeiten bei der Erstellung, ,weicher Produkte, so würde die Dokumentation sicherlich nicht Platz eins belegen. Daß Dokumentieren bei Programmierern so unbeliebt ist, dokumentiert die Unwirtschaftlichkeit der eingesetzten Methoden, wie eine kritische Bestandsaufnahme von Volker Birk* zeigt:

Das Konzept des Chief-Programmer-Teams trägt dem Umstand der Personalintensität durch die Definition eines gesonderten Tätigkeitsbereichs Rechnung. Dieser Tätigkeitsbereich umfaßt die Verwaltung von allen projektbezogenen

Informationen und wird durch den "Program Secretary" wahrgenommen. Dieses Konzept des "Program Secretary" läßt sich, jedenfalls im Bereich der Softwaredokumentation, in der Praxis nicht so effektiv realisieren, wie dies vom Konzept her erscheinen mag. Die Schwierigkeiten liegen nicht bei der mengenmäßigen Bewältigung der anfallenden Informationen, sie sind eher organisatorischer Natur.

Chief-Programmer-Team

Natürlich kann der mit der Dokumentation beschäftigte Mitarbeiter alle Programmspezifikationen, Diagramme, Entscheidungstabellen und sonstige schriftliche Fixierungen einschließlich aller Änderungen und Nachträge sammeln, ordnen und aufbereiten. Es stellt sich nur die Frage, ob ohne weitere unterstützende Maßnahmen der Projektorganisation mit einer derartigen Aktivität Wesentliches gewonnen werden kann. Soll eine Dokumentation in jeder Projektphase aktuell sein, so ist ein ständiger Update erforderlich. Bei Projekten mit mehrjährigen Laufzeiten und sehr vielen Mitarbeitern ist dieser Update mit einem nicht mehr zu vertretenden Aufwand verbunden.

Die Erstellung eines endgültigen Exemplars wird daher weiterhin bei Projektende erfolgen müssen. Es verbleibt somit nur die Möglichkeit, Änderungen und Ergänzungen zu sammeln und dem ursprünglichen Dokument zuzuordnen. Ein Projektüberblick in jeder Phase der Entstehung eines Softwareprodukts ist somit nur implizit gegeben. Fazit: Strukturierte Programmierung setzt eine ebenso geordnete Projektorganisation voraus. Ohne weitere Maßnahmen verläuft die Erstellung von Dokumentationen wie gehabt in den bekannten Bahnen. Abhilfe kann nur durch eine flexible, leicht zu wartende und modular aufgebaute Dokumentationsform geschaffen werden.

Umgangssprachliche Fixierungen

Die umgangssprachliche Fixierung der Funktion eines Programms oder eines Verfahrens allgemein bietet die größten Freiheitsgrade. Gerade hierdurch ist aber eine große Gefahr gegeben. Besitzt der Autor nicht die Disziplin, einen übersichtlichen, modularen Aufbau beizubehalten, so ist aufgrund der gestreuten Informationen ein späterer Update nahezu unmöglich. Die erstellten Dokumente müssen daher einen Standardaufbau besitzen und sich im Rahmen einer vorgegebenen, hierarchischen Gliederung exakt und eindeutig ordnen lassen. Zur Bewahrung der Eindeutigkeit darf somit kein Dokument mehrfach vorhanden sein; Zusammenhänge sind ausschließlich über Querverweise herzustellen.

Programmablaufpläne und Datenflußpläne nach DIN 66001 zählen zu den ältesten Versuchen, eine einheitliche beschreibende Darstellungsform zu schaffen. Die logischen Verknüpfungen werden durch Symbole gekennzeichnet. Auf diesem Wege ist eine klare Aussage über logische Zusammenhänge möglich. Es sind bereits Systeme realisierbar, die aus Ablaufplänen Pseudo-Source-Code erstellen. Umgekehrt ist es, bei strikter Einhaltung von Programmier-Konventionen, möglich, aus dem Source-Code eines Programms Ablaufpläne zu generieren. In beiden Fällen ist allerdings eine manuelle Vor- oder Nacharbeit erforderlich. Leider ergeben sich bei der Anwendung von Ablaufplänen nach DIN erhebliche Nachteile:

Ablaufpläne nach DIN

- Die Darstellungsweise unterstützt in keiner Weise den strukturierten Entwurf,

- Die erhöhte Übersichtlichkeit eines strukturiert geschriebenen Source-Codes kann kaum übertragen werden,

- Die Symbole in ihrer genormten Größe können zur weiteren Erläuterung bestenfalls Abkürzungen aufnehmen,

- Durch angefügte Kommentarlinien leidet die Übersichtlichkeit,

- Durch die gestreckte Form der Darstellung können oft aus Platzgründen logische Einheiten nicht zusammenhängend dargestellt werden.

Diese Nachteile führten zur Entwicklung einer Reihe von neuen Diagramm- und Tabellentechniken.

Moderne Diagrammtechniken

Aus der Fülle der neu entwickelten Diagrammtechniken sind folgende Entwicklungen besonders erwähnenswert:

- Struktogramme nach Nassi-Shneidermann,

- HIPO-Diagramme (Hierarchical input process output)

- LSS-Flowmatrizen (Large scale standard).

Durch die Anwendung der Struktogramme nach Nassi-Shneidermann, konnten im Rahmen einer zu erstellenden Dokumentation verbesserte Ergebnisse erzielt werden. Derartige Struktogramme vermeiden die wesentlichsten Nachteile der Darstellung nach DIN:

- In der Designphase wird die Schaffung einer sinnvoll strukturierten, übersichtlichen Lösung unterstützt.

- Die Struktur eines Programms, und damit eine wesentliche Komponente der Funktion, wird deutlich hervorgehoben.

- Der streng modulare Aufbau erleichtert den Update, da immer ganze "Baukästen" ersetzt werden können.

-Die Darstellung verläuft auf einer etwas höheren logischen Ebene. Hierdurch wird eine kompaktere Form der Darstellung erreicht.

- Es können relativ ausführliche Texte in die Symbole eingetragen werden.

Bei der Anwendung von anderen, neueren Techniken mögen sich ähnliche Ergebnisse erzielen lassen.

Rationalisierung

Auf der Suche nach neuen Wegen zur Rationalisierung des Dokumentationsvorgangs ist die Einbeziehung von EDV-Lösungen unerläßlich. Einige dieser Wege sind schnell und ohne größeren Aufwand zu begehen, andere erfordern vorbereitende Arbeiten, zum Teil von erheblichen Größenordnungen.

Zu den schnell und relativ mühelos zu realisierenden Zielen ist in erster Linie die strenge Standardisierung und Einhaltung von Programmier-Konventionen zu rechnen. Programme, insbesondere Assemblerprogramme, erreichen auf diesem Wege einen wesentlich höheren Grad der impliziten Selbstdokumentation.

Außerdem ergeben sich eine Reihe von Möglichkeiten zur automatischen Generierung von Dokumentationshilfsmitteln.

Realisierbar ist in diesem Zusammenhang das automatische Verwalten von Modul-Kurzbeschreibungen. Bestandteile dieser Beschreibungen können beispielsweise der Programm-Name, die gültige Versionsnummer, eine Kurzfassung der Funktion und die Call-Struktur sein. Langfristig ist die Schaffung eines einheitlichen, EDV-gerechten Notationssystems unerläßlich. Andere Disziplinen, wie die Mathematik oder die Musik, konnten nicht zuletzt durch ihre hochentwickelten Formen der Darstellung und die damit verbundene Verbesserung der Kommunikation in einem erheblichen Maße weiterentwickelt werden.

*Volker Birk ist Systemanalytiker/Programmierer bei der GfS, Gesellschaft für Systementwicklung mbH, Köln