4.1 Automatisierung des Datenimports

Bei einem Entwurf haben die Entwickler viele Daten in die Entwicklungsumgebung eingegeben. Diese Daten sind auch Grundlage der Dokumentation. Eine erneute Eingabe der Daten zum Zweck der Dokumentation ist ein zu großer Aufwand und mit der Gefahr des Konsistenzverlusts verbunden. Günstiger ist es, wenn viele dieser Informationen schon aus bestehenden Quellen stammen, z.B. der Entwicklungsumgebung oder dem Quellcode. Denn durch Übernahme der Daten aus diesen Programmen kann viel Arbeit gespart werden. Nur für zusätzliche Informationen ist dann eine Eingabe notwendig.

4.1.1 Der Datenimport aus den Entwicklungsumgebungen

Die meisten Daten für die Dokumentation stammen aus der Entwicklungsumgebung. Dort sind Daten vorhanden, wie

• Diagramme (Klassendiagramme, Szenario-Diagramme usw.)
• Klassen mit Name und einer Beschreibung der Klassen usw.
• die Beziehungen zwischen den Klassen mit Kardinalitäten
• den Methoden und Attributen mit Name und einer Beschreibung

Andere Quellen stellen auch wichtige Daten für die Dokumentation zur Verfügung, wie der Quellcode, der auch ein wichtiger Bestandteil der Dokumentation ist. In diesem Abschnitt beschäftige ich mich mit dem Import der Textdaten, da der Import von Diagrammen schwieriger ist. Die dabei auftretenden Probleme und die Lösungen zeige ich in Abschnitt 4.1.2.
Für den Datenimport gibt es zwei Möglichkeiten:

• Abfragen der Daten über Funktionen der Entwicklungsumgebung
• Auslesen der Daten aus den Dateien

Einige Programme bieten Schnittstellen für den Datenaustausch an. So hat die Entwicklungsumgebung Rational Rose eine umfangreiche OLE-Schnittstelle, mit der ein anderes Programm Objekte und die zur Verfügung stehenden Informationen aus den Diagrammen auslesen kann.
Bei dem Auslesen der Daten aus einer Datei ist das Parsen der Datei notwendig. Für die Entwicklung des Parsers ist eine Analyse der Datei erforderlich. Für das Parsen des Quellcodes nach dem Programmcode einer Methode muß zum Beispiel nach den Namen der Methoden gesucht werden. Mit den Daten aus der Entwicklungsumgebung steht der Name und die Datei, die diese Methode enthält, fest. Der Parser liest nun diese Datei, bis er den Namen findet (Kommentare überspringen). Der nun folgende Abschnitt ist der Programmcode für diese Methode. Das Ende des Programmcodes bestimmt der Parser, indem er öffnende und schließende Klammern zählt.
Ein einfacher Datenimport reicht aber meist nicht aus. In vielen Fällen sind in der Dokumentation weitere Informationen. So unterstützen einige Werkzeuge keine Versionsverwaltung. In diesem Fall muß der Entwickler die Daten hinzufügen, so muß bei einer fehlenden Versionsverwaltung der Entwickler zu jedem Objekt die Version angeben. In diesen Fällen ist es sinnvoll, daß der Importfilter die Daten, z.B. die Versionsnummer, direkt während des Lesens der Daten aus den Quellen abfragt.

Abbildung 28: Datenfluß beim Import von Daten
Die abgefragten Daten sollten in einer Datenbank abgelegt werden, so daß der in Abbildung 28 dargestellte Datenfluß entsteht. Denn eine Änderung in der Entwicklungsumgebung erfordert das erneute Ausführen des Importfilters, damit die Dokumentation auf den neuesten Stand gebracht werden kann. Der Entwickler spart viel Arbeit, wenn viele der zusätzlichen Daten in einer Datenbank schon vorliegen. Außerdem kann der Importfilter die Änderungen in der Entwicklungsumgebung erkennen, wenn er auf die alten Daten zurückgreift und so z.B. neue Versionen von den Komponenten erkennt und dann vom Anwender eine Entscheidung bezüglich der Version fordert.
Auch für die Erzeugung der Links ist eine Datenbank sinnvoll. Bei einem rein automatischen Import kann ein Programm nur entweder alle Links eines Typs erzeugen oder gar keinen. In einigen Fällen sollte der Anwender jedoch eine Auswahl treffen. So kommt eine Klasse in unterschiedlichen Klassendiagrammen vor, wie die Klasse WorkSheetCtl in den Diagrammen Gesamtdiagramm und Processing Control, einige der Klassendiagramme können zur Erklärung der Klasse dienen, wie das Diagramm Processing Control, und es sollten Links vom Inhaltsframe der Klasse zu den Diagrammen verweisen. In anderen Fällen sind diese Verweise aber nicht sinnvoll, da das Klassendiagramm keine weiteren Erklärungen über eine Klasse bietet, wie das Gesamtdiagramm, weil diese Klasse in dem Diagramm nur als Kontext für andere Klassen dient. Deshalb sollte der Anwender eine Auswahl zwischen den Klassendiagrammen treffen und entscheiden, für welche der Diagramme ein Link in den Inhaltsframe muß. Eine Datenbank mit den vielfältigen Abfragen erleichtert hier die Arbeit. Der Anwender könnte diese Links zwar auch in Schematext bearbeiten, jedoch verliert er in Schematext schnell den Überblick.
Eine Datenbank hilft auch bei der Unterstützung von unterschiedlichen Entwicklungsumgebungen, denn dafür sind unterschiedliche Importprogramme notwendig (In der Abbildung der Filter A und die OLE-Abfrage). Erzeugen die Programme direkt die SDL-Datei, so muß der Programmcode für die Erzeugung der Seite in jedem der Importprogramme stehen. Speichern diese Programme die Daten in eine Datenbank ab, so kann ein weiteres Programm aus diesen Daten die SDL-Datei generieren, so daß das Auslesen der Daten aus der Entwicklungsumgebung und das Erzeugen der HTML-Seiten entkoppelt ist.
Zum Schluß schreibt der Importfilter die Daten aus der Datenbank in die SDL-Datei von Schematext und die HTML-Dateien von FrontPage. Für jedes neue Objekt legt der Filter dazu einen Knoten mit den Unterknoten an. Den eigentlichen Inhalt der Objekte, wie einen evtl. bestehenden Text (z.B. Quelltext von den Methoden), schreibt der Importfilter in die HTML-Datei für FrontPage. Wenn Grafiken vorhanden sind, kann der Filter auch die dafür nötigen HTML-Tags in die HTML-Datei aufnehmen und gleichzeitig anhand der Koordinaten des einzelnen Objekts die Bereiche der Grafik festlegen, die die Links beinhalten. Außerdem sind die Links in die SDL-Datei einzufügen. Dabei ist zu beachten, daß eine Beziehung zwischen zwei Objekten auch zu mehreren Links führen kann. Da die Links von unterschiedlichen Frames ausgehen.

4.1.2 Probleme mit Diagrammen

Das Importprogramm, siehe Abschnitt 4.1.1, bekommt bei Diagrammen schnell Probleme. Hier ist ein direktes Schreiben in die HTML-Dateien nur in Ausnahmen durchführbar. Dies liegt an den folgenden Punkten:

• Die Diagramme aus den Entwicklungsumgebungen können keine zusätzlichen Objekte aufnehmen, z.B. für Kennzeichnung der Entwurfsmuster (vgl. Abschnitt 3.2.5).
• Die Konvertierung der Diagramme nach GIF oder JPEG Bildern (vgl. Abschnitt 3.1.1) ist von der Entwicklungsumgebung nicht möglich.

Wegen dieser zwei Punkte ist eine Nachbearbeitung der Diagramme mit einem Zeichenprogramm notwendig. Dazu importiert das Zeichenprogramm zuerst die Daten. Dafür sind unterschiedliche Vorgehensweisen denkbar:

• Ausnutzung der OLE-Schnittstelle der Entwicklungsumgebung
• Programme zur Konvertierung der Diagramme
• Neuzeichnen der Diagramme

Die erste Lösung ist die günstigste, da dort durch die Ausnutzung der OLE-Schnittstelle die Übertragung der Diagramme ohne viel Aufwand automatisch erfolgt. Jedoch muß die OLE-Schnittstelle sehr umfangreiche Funktionen besitzen, so daß nur bei wenigen Entwicklungsumgebungen die Lösung funktioniert. Bei der zweiten Lösung mit Konvertierungsprogrammen investiert der Anwender wahrscheinlich immer noch viel Arbeit, so muß er die Diagramme aussuchen und anschließend an die neuen Dateien Namen vergeben und diese auch dem Konvertierungsprogramm für die nachfolgenden Schritte bekannt machen. Da eine Entwicklung viele Diagramme enthält, ist dies arbeitsaufwendig und auch fehleranfällig. Das Neuzeichnen der Diagramme als letzte Möglichkeit hat den Nachteil, daß die Erstellung des Programms für das Neuzeichnen sehr aufwendig ist, da unterschiedliche Diagramme mit viele unterschiedlichen Objekten zu berücksichtigen sind. Durch das Neuzeichnen der Diagramme können aber die Diagramme direkt in die Werkzeugumgebung übernommen werden.
Neuzeichnen der Diagramme
In den Dateien der Entwicklungsumgebung sind die Objekte und ihre Koordinaten aufgeführt. Mit diesen Daten kann man in einem Zeichenprogramm die Diagramme nachzeichnen. Dies läßt sich natürlich automatisieren, d.h. ein Programm bekommt die Koordinaten der einzelnen Objekte übergeben, zeichnet in einer neuen Grafik an den Koordinaten die Objekte und fügt anschließend die zusätzlichen Objekte für die erweiterte Notation hinzu. Das Grafikprogramm muß die folgenden Funktionen besitzen:

• Linien zeichnen
• Text schreiben
• Flächen mit Farbe füllen und
• Grafik in JPEG oder GIF speichern.

Ein entsprechendes Zeichenprogramm selbst zu schreiben, ist sehr aufwendig. Viele der bestehenden Zeichenprogramme besitzen aber eine Schnittstelle, mit der Zeichenbefehle an das Programm übertragbar sind. So hat das Zeichenprogramm Corel Draw, das ich hier als Beispiel verwende, eine OLE-Schnittstelle, die Zeichenbefehle verarbeitet. Es existieren aber auch weitere Programme, wie VISIO, die auch benutzt werden können.
Hier ein einfaches Beispiel: ein Klassendiagramm mit nur einer Klasse. Damit ein Programm das Diagramm zeichnen kann, muß es die OLE-Schnittstelle von Corel-Draw benutzen. Nach dem Initialisieren der Schnittstelle steht dem Programm ein OLE-Automatisierungsobjekt zur Verfügung. Für das Zeichnen dieses Klassendiagramms muß Corel Draw die folgenden Funktionen des Objektes aufrufen:

Problem bei dem Neuzeichnen der Diagramm sind die vielen Elemente, die zu berücksichtigen sind. Schon bei den Klassendiagrammen sind unterschiedliche Klassentypen, wie Class, Parameterized Class, Instanziated Class usw. und unterschiedliche Beziehungstypen, wie Vererbung, Benutzt-Beziehung, Aggregation usw. vorhanden. Zu diesen gibt es noch viele unterschiedliche Attribute, wie Kardinalzahlen oder Rollen, die auch in der Zeichnung sind. Zusätzlich existieren noch weitere Diagrammtypen, die alle eine eigene Notation besitzen.

Zeichnen der zusätzlichen Notation

Für das automatische Zeichnen der zusätzlichen Notation, wie die Kennzeichnung der Entwurfsmuster, sind viele Informationen zu berücksichtigen. Viele Informationen sind vom Anwender einzugeben. Er bestimmt die Klassen, die zu einem Entwurfsmuster gehören und die Klassendiagramme, in die die Entwurfsmuster zu zeichnen sind.
Andere Informationen können eventuell auch errechnet werden. So sind ja alle Positionen der Klassen in einem Klassendiagramm bekannt. Ein Algorithmus kann nun die Kennzeichnung der Entwurfsmuster durchführen. Der Ablauf könnte sein:

1. Zeichne eine rechteckige Fläche, so daß es alle Klassen des Entwurfsmusters umschließt.
2. Ermittle, ob Klassen, die nicht zu dem Entwurfsmuster gehören, auch markiert sind. Wenn nein, fertig.
3. Schneide vom Rand der Fläche Rechtecke aus, so daß diese Klassen nicht markiert sind.
4. Ermittle, ob die Fläche noch zusammenhängt. Wenn ja, weiter mit Schritt 6.
5. Zeichne ein zusätzliches Rechteck, ohne eine ausgeschnittenes Rechteck erneut zu markieren, so daß die Fläche wieder zusammenhängt
6. Ermittle, ob Klassen, die zu dem Entwurfsmuster gehören, nicht mehr markiert sind. Wenn nein, fertig.
7. Füge neue Rechtecke zu der Fläche hinzu, so daß diese Klassen wieder markiert sind.
8. Gehe zu Punkt 2.

Corel Draw zeichnet nun diese Fläche als Linse in die Zeichnung, dabei ist, genauso wie bei dem Zeichen der Klassen, die OLE-Schnittstelle zu nutzen. Der Text für das Entwurfmuster ist nun an den Rand zu schreiben. Dabei ist darauf zu achten, daß keine Klasse überschrieben wird.
Für die weiteren Entwurfsmuster ist genauso vorzugehen. Nur die Abstände der Fläche zu den Klassen sollten variieren, damit die Flächen der Entwurfsmuster auch bei überlappenden Teilen noch unterscheidbar sind. In der Abbildung 22 ist eine solche Überlappung bei der Klasse CNC_Maschine.