Damit die Dokumentation sinnvoll ist, sollte sie vollständig und möglichst verständlich sein. Damit die Dokumentation vollständig ist, muß sie alle Texte und Diagramme aus der Softwareentwicklung beinhalten. Deshalb zeige ich im ersten Anschnitt dieses Kapitels die Dokumente, die bei der Softwareentwicklung entstehen. Danach folgt ein Abschnitt, der eine Möglichkeit zeigt, die Dokumentation verständlicher zu gestalten. In diesem Abschnitt geht es um die Dokumentation mit Entwurfsmustern.
Die Dokumentation dient zum Festhalten und Verdeutlichen des Entwurfs. Deshalb müssen in einer Dokumentation alle bei der Entwicklung entstehenden Texte und Diagramme enthalten sein. Deshalb stelle ich im folgenden vor, welche Dokumente während des Entwurfs entstehen und welche Form sie besitzen. Dazu werden zwei verbreitete Vorgehensmodelle mit den entstehenden Dokumenten vorgestellt.
Abbildung 2: Das Wasserfallmodell [Pagel & Six, 1994]
Das Wasserfallmodell ist ein einfaches Modell für das Vorgehen bei der Softwareentwicklung. Es teilt die Softwareentwicklung in einzelne Abschnitte ein, siehe Abbildung 2. Im Lebenszyklusmodell wird zu dem Wasserfallmodell als letzte Phase noch die Phase Einsatz und Wartung hinzugefügt. Die einzelnen Phasen des Wasserfallmodells sind noch weiter unterteilt. Die erste Phase in der Softwareentwicklung ist die Analyse und Definitionsphase [Pagel & Six, 1994]. Sie dient zur Analyse der Anforderungen. Die Analytiker müssen im Gespräch mit den Auftraggebern und den Benutzern oder durch die Analyse der bestehenden Programme oder Arbeitsabläufe die benötigten Funktionen der Software herausfinden. Dazu ist die Analyse und Definitionsphase in drei Unterphasen unterteilt:
In der Vorstudie werden die groben Anforderungen ermittelt und in einer Produktskizze festgehalten. Diese Produktskizze dient zur Planungsgrundlage und Entscheidungsgrundlage für den Auftraggeber und das Management, ob das Projekt durchgeführt werden soll. Die Produktskizze ist in natürlicher Sprache geschrieben, die durch Graphiken und Tabellen ergänzt wird. Die Graphiken können zum Beispiel Klassendiagramme oder auch wichtige Geschäftsvorfälle als Use Cases sein. Bei der Projektplanung werden die Kosten und der Bedarf an Personal abgeschätzt und das weitere Vorgehen geplant. Aufgrund dieser Daten entscheiden der Auftraggeber und das Management über die Durchführung des Projektes. Der letzte Schritt, die Anforderungsermittlung, dient zur vollständigen Ermittlung der Anforderungen. Die hier erstellten Dokumente beschreiben die Anforderungen, die die Software erfüllen soll, damit sie in den folgenden Phasen verwirklicht werden können. Dazu werden die Objekte der realen Welt gesucht und diese in Klassen eingeordnet. Die so gefundenen Klassen bekommen auch die notwendigen Attribute und Funktionen, damit sie ihre Aufgabe erfüllen können. Die Klassendiagramme mit den gefundenen Klassen beinhalten zusätzlich die Beziehungen zwischen den Klassen. Ebenfalls werden die Geschäftsvorfälle (Use Cases) genauer spezifiziert. Texte ergänzen die Informationen in den Diagrammen und erklären die Aufgaben der Klassen. Für Teile der Analyse können auch andere Diagramme sinnvoll sein, so zum Beispiel Zustandsübergangsdiagramme, die das Verhalten einer Klasse zeigen, oder auch Objektscenarien, die die Abläufe genauer darstellen.
Beim Entwurf wird gefragt, wie das Projekt verwirklicht werden soll. Dazu teilt sich der Entwurf ebenfalls in drei Unterphasen:
Da beim objekt-orientierten Vorgehen keine großen Brüche zwischen den einzelnen Phasen bestehen, können beim Grobentwurf einfach die Klassendiagramme übernommen werden. Es ist nur eine Einteilung in Module notwendig, um die anfallenden Arbeiten auf mehrere Personen zu verteilen. Dadurch entstehen Diagramme, die die Klassen einem Modul zuordnen. Bei anderen Vorgehensweisen, wie der Modernen Strukturierten Analyse (MSA), dient diese Phase zur Überführung des Analysemodells in ein Modell für den Entwurf und ist umfangreicher. Ein wesentlicher Punkt beim Feinentwurf ist die Wiederverwendung und die Redundanzvermeidung. Die Klassendiagramme aus dem Grobentwurf enthalten noch Redundanz. Neue Vererbungshierarchien in abgeänderten Klassendiagrammen können diese Redundanz verringern, indem sie die redundanten Teile in abstrakten Klassen zusammenfassen. Diese abstrakten und weitere Klassen helfen auch später bei der Weiterentwicklung der Software, da durch sie meist mehr wiederverwendet werden kann und die Struktur durch geeignete Verbesserungen, z.B. Nutzung von Entwurfsmustern, wesentlich flexibler ist. Um vorhandene Module, z.B. Klassen für die Benutzeroberfläche, verwenden zu können, sind weitere Änderungen in den Klassendiagrammen notwendig. Alle Änderungen in den Klassendiagrammen bewirken auch Änderungen in den Klassen, in denen sich Methoden und Attribute verändern oder hinzukommen. Diese Änderungen müssen auch in den Texten festgehalten werden, die die Klasse beschreiben. In der Entwurfphase sind aber noch weitere Betrachtungen notwendig. In vielen Fällen sind weiter Klassen aus technischen Gründen erforderlich, z.B. um eine bestimmte Performanz zu erreichen. Die Datenhaltung erfordert auch eine Betrachtung. Die persistenten Daten müssen ermittelt werden. Außerdem erfolgt die Speicherung der persistenten Daten zum Teil noch mit relationalen Datenbanken, so daß eine Abbildung der Daten notwendig ist. Der Implementierungsentwurf dient zur Vorbereitung der Implementierung. In dieser Phase erfolgt die Anpassung des Entwurfs an die Programmiersprache. Diese Anpassung ist notwendig, wenn die Programmiersprache nicht alle verwendeten Konstrukte unterstützt, z.B. die mehrfache Vererbung.
In der daran anschließenden Implementierungsphase werden die Methoden der Klassen programmiert. Erst in dieser Phase entsteht der Quellcode. In der letzten Phase, der Testphase, wird die Software untersucht, ob sie die Anforderungen erfüllt und ob sie fehlerfrei ist. An dem hier dargestellten Wasserfallmodell gibt es viele Kritikpunkte.
Aus diesem Grund gibt es von diesem Modell viele Erweiterungen. Eine wesentlicher Kritikpunkt ist, daß bei dem Wasserfallmodell keine Rückschritte möglich sind. Ist zum Beispiel einmal die Analysephase abgeschlossen und man ist im Entwurf, so können Fehler aus der Analysephase nicht mehr korrigiert werden. Außerdem ist für den Test eine einzelne Phase vorgesehen. Bei der Softwareentwicklung müssen die erzeugten Dokumente aber ständig auf ihre Korrektheit überprüft werden. In der Analyse gemachte Fehler, deren Entdeckung erst in der Testphase erfolgt, sind sehr schwerwiegend, da die Ergebnisse der Entwurfsphase und der Implementierungsphase nicht mehr verwendbar sind und diese Phasen erneut durchlaufen werden.
Das Bundesministerium für Verteidigung hat ein
Vorgehensmodell, daß V-Modell (Abbildung 3), entwickelt und
Firmen, die für das Ministerium Software entwickeln, müssen
nach diesem Vorgehensmodell vorgehen [Bröhl & Dröschel,
1995]. Später hat das Bundesministerium des Inneren das V-Modell
übernommen. Alle Softwareentwicklungsfirmen müssen bei der
Entwicklung von Software für diese Ministerien nach dem V-Modell
vorgehen. Außerdem wird das Modell inzwischen auch für Projekte
benutzt, die nicht mit den Ministerien in Zusammenhang stehen. 
Abbildung 3: Das V-Modell (Submodell Softwareerstellung) [Bröhl & Dröschel, 1995]
Das V-Modell umfaßt vier Submodelle:
Für alle vier Submodelle ist vorgegeben, welche Tätigkeiten auszuführen sind. Für jede Tätigkeit gibt es Vorgaben, die beschreiben, welche Dokumente aus anderen Tätigkeiten vorhanden sein müssen, bevor die neue Tätigkeit begonnen werden kann. Diese Daten sind in Tabellen zu den einzelnen Tätigkeiten festgehalten. In den Tabellen ist auch die Person (z.B. Systemanalytiker und Systemdesigner) definiert, die die Tätigkeit ausführt. Die Dokumente, die durch diese Tätigkeit entstehen, sind ebenfalls definiert. Da die Dokumente meist wieder Vorgaben für nachfolgende Schritte sind, ist für jedes Dokument ein Zustand definiert. Ein Dokument kann in Bearbeitung, vorgelegt oder akzeptiert sein. Diese drei Zustände ermöglichen das Qualitätsmanagement. Denn erst nach dem Akzeptieren des Dokumentes durch die Qualitätskontrolle darf das Dokument in den folgenden Tätigkeiten verwendet werden. Die Tätigkeiten bauen also, ähnlich wie im Wasserfallmodell, aufeinander auf. Die in der Abbildung 3 dargestellten Tätigkeiten sind die Haupttätigkeiten der Softwareentwicklung. Diese gliedern sich in kleinere Abschnitte. Das ganze Vorgehensmodell ist sehr komplex. Es ist auch für die Entwicklung von Systemen geeignet, in denen Software nur ein Teilsystem ist. Aus diesem Grund sind auch die Phasen Systemanforderungsanalyse (Teil von SWE1), DV-Anforderungsanalyse (Teil von SWE2) und SW-Anforderungsanalyse (SWE3) vorhanden. Die Systemanforderungsanalyse dient zur Analyse des Gesamtsystemes, die DV-Anforderungsanalyse zur Analyse der Datenverarbeitungskomponete (Hardware und Software) und die SW-Anforderungsanalyse zur Analyse der Softwarekomponente. Bei kleineren Systemen können einige Tätigkeiten unter bestimmten Bedingungen ausgelassen werden, diesen Vorgang nennt man Tailoring. Für jede Phase sind die Dokumente definiert, die in der Phase entstehen und der nächsten Phase als Vorgaben dienen. So ist, wie in Abbildung 3 dargestellt, für den Übergang von dem Grobentwurf SWE 4 zum Feinentwurf eine Softwarearchitektur, ein Schnittstellenentwurf und ein Integrationsplan notwendig. Der Inhalt der Dokumente ist ebenfalls vorgegeben, so ist für die Softwarearchitektur ein Dokument mit den folgenden Kapiteln notwendig:
Dabei unterteilen sich einige der Kapitel noch weiter, z.B. der Prozeßentwurf. Für die einzelnen Kapitel ist der Inhalt vorgegeben und gleichzeitig eine geeignete Darstellungsform empfohlen. So sind die Kapitel Allgemeines (0), Zweck des Dokumentes (1), Lösungsvorschläge (2) und Anforderungszuordnung (5) reine Textdokumente. Für die Kapitel Prozeßentwurf (3) und Modularisierung / Datenbankentwurf (4) ist eine Mischung aus graphischer und textueller Darstellung vorgesehen. Das Submodell Qualitätssicherung beschreibt die Tätigkeiten zur Sicherung der Qualität der Software. Die Ergebnisse der einzelnen Abschnitte in der Softwareentwicklung sind jeweils zu überprüfen. Dazu ist jeweils ein eigener vorgegebener Ablauf durchzuführen. In der Entwicklungsphase wird dabei überprüft, ob die Entwicklung die Anforderungen aus der vorherigen Phase erfüllt. In der Implementierungsphase wird überprüft, ob die Anforderungen des entsprechenden Entwicklungsabschnittes erfüllt werden.
Die Dokumentation mit Entwurfsmustern ist eine Weiterführung des Entwurfs mit Entwurfsmuster. Durch die beschreibende Eigenschaft der Entwurfsmuster [Odenthal & Quibeldey-Cirkel, 1997] helfen die Entwurfsmuster beim Verständnis für den Entwurf.
Abbildung 4: Klassendiagramm ohne Entwurfsmuster
In Klassendiagrammen ohne Entwurfsmuster sind viele Klassen mit entsprechend vielen Beziehungen, siehe Abbildung 4. Die Klassen und die Beziehungen sind zwar bezeichnet, jedoch findet ein Leser nur schwer einen Einblick in die Diagramme. Der Leser hat keinen Anhaltspunkt, welche Klassen und Beziehungen für das Verständnis wichtig sind. Es ist eine weitere Strukturierung wichtig. Entwurfsmuster bieten diese Strukturierung, wenn der Leser die Entwurfsmuster kennt. Insbesondere die abstrakten Klassen in den Diagrammen werden durch das Entwurfsmuster verständlich. Ohne die erklärende Funktion der Entwurfsmuster ist das Verständnis für die abstrakten Klassen sehr gering. Ist diese Klasse jedoch Teil eines Entwurfsmusters, kann der Sinn dieser Klasse leicht verständlich gemacht werden. Denn dann erkennt der Leser den Sinn der Klasse, indem er zwischen dieser Klasse und der entsprechenden Klasse im Entwurfsmuster Parallelen zieht. Die Beziehungen zwischen den Klassen können ebenfalls durch Entwurfsmuster verdeutlicht werden. Ohne Entwurfsmuster besteht zwischen den Klassen nur eine einfache Benutzt-Beziehung. Ist diese Beziehung Teil eines Musters, bekommt diese Beziehung einen besonderen Sinn. So ist das Diagramm in Abbildung 4 leichter verständlich, wenn man die Entwurfsmuster kennt und weiß, daß die Klassen das Entwurfsmuster Adapter bilden und dabei die Klassen in dem Diagramm die folgenden Funktionen im Entwurfsmuster haben: ProcessingControl Client Machining Target CNCMachining, PLCMachining Adapter CNCMachine Adaptee
Abbildung 5: Klassendiagramm mit Entwurfsmuster
Diese Beziehungen sind auch in dem Klassendiagramm darstellbar (Abbildung 5). Bei der Dokumentation muß auch der Entwurf mit Entwurfsmustern berücksichtigt werden. Nach [Odenthal & Quibeldey-Cirkel, 1997] kann das Vorgehen zur Nutzung von Entwurfsmustern beim Entwurf in vier Schritten unterteilt werden:
In allen diesen Schritten werden Entscheidungen
getroffen und die Struktur der Beziehungen zwischen den Klassen
sowie die Klassenschnittstellen verändert sich, wie in Abbildung
6 dargestellt. Beim ersten Schritt sucht der Entwickler das
geeignete Muster. In einigen Fällen sind mehrere Entwurfsmuster
geeignet. Alle diese Entwurfsmuster bieten eine bestimmte
Flexibilität im Entwurf an. Somit muß der Entwerfer
entscheiden, an welchen Stellen der Entwurf flexibel sein muß
und danach das Entwurfsmuster aussuchen, daß diese Flexibilität
bietet. Meist bedeutet dies aber, daß der Entwurf an anderer
Stelle unflexibel ist. So erleichtert das Entwurfsmuster Visitor
das Hinzufügen von neuen Operationen, jedoch das Hinzufügen von
neuen Klassen "ConcreteElement" ist schwierig [Gamma et
al., 1995]. 
Abbildung 6: Die vier Schritte beim Einsatz von Entwurfsmustern [Odenthal & Quibeldey-Cirkel, 1997]
Im zweiten Schritt müssen die Klassen des
Musters in die Klassen des Problembereichs übertragen werden.
Dazu muß der Entwickler die Rollen innerhalb des Musters auf die
Klassen, Methoden und Attribute des Problembereiches verteilen.
Dabei lassen sich die Rollen des Musters meist nicht direkt in
den Problembereich übertragen. In diesem Fall muß entweder ein
anderes Entwurfsmuster genommen werden oder die Struktur der
Klassen des Problembereichs muß verändert werden. Der Entwerfer
nimmt im dritten Schritt die notwendigen Anpassungen vor. So
können neue Klassen zum Problembereich hinzugefügt werden.
Diese Klassen sind meist die abstrakten Klassen des Musters.
Andererseits können auch Klassen oder Beziehungen des Musters
verändert oder weggelassen werden. In einigen Fällen muß nur
eine Klasse von einer abstrakten Klasse eines Entwurfsmusters
abgeleitet werden, in diesem Fall kann die abstrakte und die
abgeleitete Klasse zusammenfallen. Nun folgt im letzten Schritt
das Hinzufügen der technischen Klassen. In vielen Fällen sind
technische Klassen für die Verwaltung nötig, z.B. Klassen für
Listen oder Mengen. Zusätzlich kann auch die Erweiterung der
Klassenschnittstelle nötig sein. Die Entscheidungen, die der
Entwerfer bei der Auswahl und dem Einsatz getroffen hat, sind in
der Dokumentation festzuhalten. So hat der Entwerfer ein
bestimmtes Entwurfsmuster ausgewählt, damit der Entwurf an einer
bestimmten Stelle flexibel ist. Bei nachträglichen Änderungen
muß nun darauf geachtet werden, daß die Struktur des
Entwurfsmusters erhalten bliebt, damit die Flexibilität weiter
gewährleistet ist. Auch Änderungen in der Struktur der Klassen
gegenüber der Struktur des Originalmusters sind festzuhalten, da
für diese ein Grund existiert und deshalb auch bei
nachträglichen Änderungen zu berücksichtigen sind.