Folgend stellen wir dar, was Software-Dokumentation mit Entwurfsmustern ist und wie durch sie die Qualität und Verwendbarkeit und somit der Stellenwert der Dokumentation entscheidend verbessert werden kann. Bei dieser Art des Einsatzes von Mustern geht es nicht darum, neue Muster zu finden und zu beschreiben, sondern Musterbücher (auch eigene) zu verwenden. Das Vorgehen ist die Weiterführung des mustergestützten Entwurfs. Wurde ein Entwurf annähernd vollständig mit Mustern abgedeckt, stellen die Musterausprägungen die Ausgangsbasis für die Entwurfsdokumentation dar. Durch sie wurde das entwickelte System strukturiert und eine Abstraktionsebene oberhalb der Klassen geschaffen, der Entwurf unabhängig vom Problembereich semantisch strukturiert (Meta-Semantik). Die Dokumentation mit Entwurfsmustern stellt den Bezug zum Problembereich her: sie ist die Erklärung, warum und wie das Muster ausgeprägt wurde.
Die Idee besteht darin, die Musterform auch als Strukturierung für die Dokumentation zu verwenden (Tabelle 1). Hierdurch und durch die bestehende Strukturierung des Entwurfs mit Mustern, ist die Entwicklungsdokumentation vollständig vorstrukturiert, was das Dokumentieren erleichtert. Die so erreichte Trennung von Struktur und Inhalt der Dokumente ist eine wichtige Voraussetzung für die Konsistenzerhaltung zwischen Entwurf und Dokumentation sowie für eine Repräsentation als Hypertext. Derart strukturierte Dokumente eignen sich schließlich gut für die Verwendung in Retrieval-Systemen [11]. Mit adäquater Werkzeug-Unterstützung kann aus der passiven schnell überholten Papierdokumentation ein aktives Informationssystem werden. Die Dokumentation der Entwurfsentscheidungen erfolgt dann iterativ und verzahnt mit der eigentlichen Tätigkeit des Entwerfens.
| Übersicht | Ein Klassendiagramm und evtl. weitere Visualisierungen, die zur Verdeutlichung geeignet sind. |
| Intention | Die knappe Beschreibung der wesentlichen Intention. Der Grund, warum genau dieses Muster ausgeprägt wurde, sollte deutlich werden. |
| Motivation | Die Ausführliche Beschreibung der Zusammenhänge. Übersicht über die Komponente. Es kann sinnvoll sein, die "Entwicklungsgeschichte" anhand des Vorgehens zur Musterausprägung zu illustrieren. Auch Verweise auf Dokumente aus der Analysephase (z.B. der Bezug zu fachlichen Mustern). |
| Rollen | Hinter die Klassen des Musters werden die Klassen der Implementierung geschrieben. Diese Zuordnung ist für den Leser hilfreich, der das Muster kennt und sich über die spezielle Ausprägung informieren will. Eine stichpunktartige Beschreibung der Rolle, die die Klasse in der Musterausprägung einnimmt. |
| Zusammenarbeit | Beschreibung der Interaktion zwischen den Klienten und der Musterausprägung. |
| Konsequenzen | Beispielsweise die Erweiterbarkeit, Vergleich mit anderen Realisierungen, Einschränkungen. |
| Implementierung | Besonderheiten der Implementierung. |
Tabelle 1: Gliederung für die Dokumentation von Musterausprägungen
Frameworks sind wertvoller als andere Komponenten, da sie wesentlich teurer in der Entwicklung waren (Praxiserfahrungen liegen bei einem Faktor von 4-5) und in weiteren Projekten wiederverwendet werden sollen. Wir unterscheiden daher zwischen der Dokumentation von bereichsspezifischen Komponenten, bei der die Wiederverwendung nicht im Vordergrund steht, sondern "nur" die möglichst einfache Nachvollziehbarkeit der Entwurfsentscheidungen, und der Dokumentation von Frameworks zur Wiederverwendung (Tabelle 2).
Noch zwei Bemerkungen: Auf Gliederungspunkte
für die Musterverwaltung in Bibliotheken und die Zuordnung zu
Bearbeitern und dem Vorgehensmodell (Versions- und
Prozeßmanagement) haben wir hier verzichtet.
Derartige Gliederungen lassen sich in modifizierter Form auch
erfolgreich für die Dokumentation auf Klassen- und
Operationsebene einsetzen [8].
| Hot Spots, Frozen Spots |
Für die Dokumentation von Frameworks ist die gesonderte Beschreibung der festgelegten Eigenschaften des Frameworks und der durch den Benutzer anzupassenden bzw. zu erweiternden Komponenten essentiell (vgl. [9]). Aus dieser Beschreibung sollte eindeutig hervorgehen, welche Flexibilität vom Framework zu erwarten ist und wo dessen konzeptionelle Grenzen sind. |
| Rezept | Der Cookbook-Stil wurde u.a.
von Johnson [6] verwendet, um den Einsatz eines Frameworks
anhand eines schrittweisen, durch Beispiele ergänzten
Vorgehens zu verdeutlichen. Diese Beschreibung kann durch
ein Ready-to-use-Beispiel, das die direkte
Ausführung und somit das Ausprobieren eines Frameworks
erlaubt, ergänzt werden. Auch eine vorkonfigurierte
Debugger- Sitzung eignet sich zum besseren Verständnis. Ist eine feste Entwicklungs- und Laufzeitumgebung vorhanden, bilden interaktive Hilfen für die Nutzung eines Frameworks (Assistenten, Wizzards) das Optimum an Unterstützung für den Anwender. |
| Integrierbarkeit | Wie paßt sich das Framework in bestehende Umgebungen ein? (Beispielsweise Portabilität, Realisierung der Ausnahmebehandlung). |
| Verwendungen | Anhand der Verweise auf Einsatzbeispiele kann der Anwender am schnellsten die Eignung des Frameworks überprüfen. |
| Strukturelle Erweiterungen | Vor allem bei Inhouse-Entwicklungen kann es sinnvoll sein, den Entwurf eines Frameworks eingehend zu beschreiben, um dessen Erweiterbarkeit zu erleichtern. Ein Framework durchläuft mehrere Designzyklen, bis die Hot Spots identifiziert sind und so das richtige Maß an Flexibilität erreicht wurde. Wird es in bisher nicht vorgesehenen Bereichen eingesetzt, kann eine Erweiterung nötig sein. Aus beiden Gründen ist die Dokumentation des Entwurfs sinnvoll. |
Tabelle 2: Erweiterte Gliederung für die Dokumentation von Frameworks
In Bild 1 ist die Einordnung der Dokumentation mit Entwurfsmustern in eine Abstraktionshierarchie der Dokumente dargestellt. Zuoberst steht die Beschreibung der Systemeigenschaften. Aus diesen Dokumenten verzweigt der Leser in die Dokumentation der Komponenten, die auf der Abdeckung eines Entwurfs mit Musterausprägungen basiert. Von diesen Dokumenten gelangt er zu den Beschreibungen der Klassen und von dort auf die Implmentationsebene. Die dreifachen Pfeile im Bild symbolisieren die sich ergebende Struktur des Gesamtdokuments: ein Hypertext-Baum.
Bild 1: Die Einordnung der Dokumentation mit Entwurfsmustern
Beispiele zur Dokumentation mit Entwurfsmustern momentan nur als Hypertext im WinHelp-Format von Windows 95/NT (311k als ZIP-Archiv).