Programmdokumentation -
        Techniken und Werkzeuge   

Muß das wirklich sein...

Den meisten Entwicklern sind die guten Gründe für das Erstellen einer Programmdokumention geläufig. Den restlichen werden sie normalerweise mit der Zeit durch Einsicht oder äußeren Druck nahe gebracht. Hier gibt es die allseits beliebten Szenarien, in denen ein anderer Entwickler (oder gar man selbst) sich in einem wenige Monate alten Projekt nicht mehr oder erst nach heftiger Einarbeitung zurechtfindet, oder indem ein neuer Auftrag an der Frage scheitert: "Zeigen Sie uns doch einmal die Dokumentation ihres letzten Projektes".

Hinweise auf die hoffentlich reichlich vorhandenen, in den Sourcen befindlichen Kommentare, auf Metadaten (Datenstrukturen, Klassenbibliotheken) helfen hier in der Regel nur wenig weiter. Diese vorhandenen Daten müssen visualisiert, d.h. optisch so aufbereitet werden, damit Sie vorzeigbar sowie - was meiner Meinung nach wesentlich wichtiger ist - einfach und effizient nutzbar sind.

Visualisieren bedeutet in der Windows-Welt normalerweise, daß die angezeigten Informationen in gleicher Form ausgedruckt werden können, womit man dann gleichzeitig über eine vorzeigbare, gedruckte Dokumentation verfügt.

Aktuelle Dokumentation?

Eine gedruckte Dokumentation mag zwar schön aussehen und gelegentlich dabei helfen einen neuen Auftrag zu erhalten. Für diejenigen, die jedoch diese Unterlagen eigentlich benutzen sollten und manchmal auch wollen, sind sie allerdings oft ein ziemliches Ärgernis. Dieses Gefühl stellt sich immer dann ein wenn es sich herausstellt, daß die Dokumentation irgendwie nicht so ganz zu dem vorliegenden Programm paßt:

• dokumentierte Struktur-Eigenschaften (z.B. Properties) fehlen
• oder sind vorhanden aber nicht dokumentiert
• Oberflächenelemente sind offensichtlich anders
• Schnittstellen sind anders (Anzahl + Typ der Parameter, andere Methodennamen...)
• Es werden Begriffe benutzt, die zu einem anderen Programm gehören (Doku-Kopie)

Diese Abweichungen zwischen dem zu dokumentierenden Programmsystem und der Dokumentation haben zudem ein recht dynamisches Eigenleben. Die Ursache dafür sind zumeist die diversen, jedem Entwickler oder Projektleiter bekannten, oft nur wenig zu beeinflussenden Parameter eines Softwareprojektes: "begrenzte Zeit" und "begrenzte Ressourcen". Diese führen oft dazu, daß nicht die eigentlich notwendige Arbeitszeit in die Aktualisierung der Dokumentation gesteckt wird oder gesteckt werden kann ("Die sieht ja auch so gut aus...").

In der Praxis der Softwarentwicklung scheint es daher ein bisher noch nicht näher beschriebenes Naturgesetz zu geben und zwar das

Diese überschlägige Formel liefert, relativ unabhängig von der Größe des eingesetzten Korrekturfaktors K, ein für den Nutzer der Dokumentation fast immer frustrierendes Ergebnis.

Aktuelle Dokumentation!

Ausgehend von der Einsicht, daß der Versuch, eine vorhandene Dokumentation aktuell zu erhalten immer von der ausreichenden Verfügbarkeit der hierfür verfügbaren Ressourcen abhängig ist, bietet sich eigentlich nur der Ausweg an, zeitnah eine neue Dokumentation direkt aus den Sourcen zu erstellen und das weitgehend automatisiert.

Der Aufwand, der für den Zugriff auf die Sourcen und die notwendige Aufbereitung und spätere Ausgabe notwendig ist, hängt sehr stark davon ab, in welcher Form die Sourcen vorliegen und wie einfach der Zugriff darauf ist. Hier sind die Visual Foxpro-Entwickler einmal mehr auf der Sonnenseite der Entwicklergemeinde, da VFP fast alle Programmsourcen in normalen DBF-Dateien ablegt. Mit bordeigenen Mitteln lassen sich daraus bereits mit recht wenig Aufwand sehr ansehnliche Ausdrucke erzeugen. Die so erhältlichen Informationen beschränken sich jedoch im wesentlichen auf Strukturinformationen, wie z.B. Namen von Klassen, Methoden und Properties inclusive der zugehörigen Kommentare, Klassenhierarchien und deren Verteilung auf Klassenbibliotheken usw.

Will man weitergehende Infos zugänglich machen, so muß man ein klein wenig mehr tun...

Vollwert-Dokumentation

Eine Dokumentation sollte wenn möglich weitere Informationen enthalten, wie z.B.:

• Versions Hinweise (z.B. Änderungshistorie)
• Parameter und deren Beschreibungen
• "Zu erledigen"-Hinweise
• Anwendungs-/Aufrufbeispiele
• Hinweise für Entwickler

Um diese Informationen für ein Dokumentationstool leicht zugänglich zu machen, reichen einige wenige Konventionen zum Thema "wie und wo sollen Doku-relevante Infos abgelegt werden". Wie im bereits aufgeführten Gesetz beschrieben hat der zeitliche/räumliche/logische Abstand zwischen Dokumentation und Sourcen zumeist erheblichen Einfluß auf die Qualität derselben. Dies liegt u.a. daran, daß eine externe, von den Sourcen getrennt gehaltene Dokumentation zusätzlichen Aufwand sowohl für die Bearbeitung (i.d.R. nicht das Entwicklungstool) als auch für die Erhaltung/Verwaltung der Versionsgleichheit bedeutet. Es liegt daher nahe, die entsprechenden Infos direkt im Sourcecode abzulegen. Die Vorteile hiervon sind recht einleuchtend:

• Die Entwickler müssen keine separaten Dokumente pflegen
• Doku-Hinweise gehören zwangsläufig zur aktuellen Source-Version
• Hinweise und ToDo's werden direkt dort abgelegt, wo sie auf etwas hinweisen können/sollen
(Doku-Alzheimer-Prävention)

Dem Entwickler kann man dann noch kleine Hilfen für das einfache Anlegen Doku-relevanter Einträge in den Sourcen bieten, wie Funktionen, die direkt entsprechende Code Blöcke einfügen. Ein Beispiel hierfür ist eine Wer/Wann-Markierung wie "*! 11.11.98 Joachim:", die sich dehr einfach per Hotkey einfügen läßt:

keyboard  left( CDOW(date()),2) +" "+ dtoc(date()) + " " ;
         + trim(left(Sys(0), at(" ",sys(0)))) +":"

Arten der "Inline"-Dokumentation

Unter den innerhalb der Sourcen "versteckten" Dokumentationstexte können diverse Arten unterschieden werden:

• Ein-/mehrzeilige Kommentare zur Erklärung von Programmabläufen
  Sie dienen hauptsächlich dem leichteren Verständnis eines Codeblocks und sind relativ uninteressant für die externe Dokumentation.
• Auskommentierter alter Code
  Wird in der Regel nur für den Fall benötigt, daß der neue Code wider Erwarten nicht funktionieren sollte.
• Schnittstellenbeschreibung
  Hierunter fällt die Beschreibung der Aufruf parameter und der Rückgabewerte
  Eigentlich ein Muß für jeden Entwickler
• Versionsbeschreibung/Änderungshistorie
  u.a. Namen neuer/geänderter Parameter, Methoden und Properties
  
• Diese Art der Doku wird immer dann besonders hilfreich, wenn ein Fehler auftritt und man schnell in der Lage ist zu erkennen, ob er lediglich bisher nicht aufgetreten ist oder durch eine Änderung in einem anderen Programmteil ausgelöst wurde. Hinweise auf notwendige, noch durchzuführende Änderungen z.B. "für ORACLE muß hier noch ... " Diese Hinweise sind sehr hilfreich, wenn Funktionen aus Zeitmangel nicht sofort für alle zukünftig möglichen oder vorgesehenen Fälle ausprogrammiert werden können.

Wohin damit?

Alle beschriebenen Doku-Arten können direkt dort abgelegt werden, wo sie auf etwas Hinweisen sollen, bzw. wo der Entwickler gerade seinen Code bearbeitet hat. Für einige Arten bietet es sich allerdings an, sie entweder ganz oder zusätzlich an anderen Stellen abzulegen.

Schnittstellenbeschreibungen sollten (auch) im Kommentar einer Methode auftauchen, wie z.B. "liefert eindeutigen Wert für das Feld A000 *!P , *!P " Über den Kommentar kann ein Entwickler jederzeit im Eigenschaftenfenster sehen, daß hier zwei Parameter benötigt werden und von welchem Typ diese sein müssen.

Betrachtet man ganze Klassen, so wird dies schon etwas schwieriger, da hier ja u.U. auch Strukturänderungen (neue/geänderte Properties und Methoden) nachvollzogen werden müssen. Hier bietet es sich an, seinen Klassen standarmäßig eine Methode mit dem Namen _Dokumentation() zu spendieren. In diese Methode kann, beliebig viel Text abgelegt werden:

#IF .f.    &&  der folgende Text wird nicht eincompiliert
11.11.98 Joachim: Neue Methode MeineMethode()
#ENDIF

Durch die #IF .F. - #ENDIF Konstruktion wird verhindert, daß der Compiler versucht, den dazwischen stehenden Text zu kompilieren.

Mit dem auf der Begleit-CD befindlichen (ziemlich alten) Klassenbibliothek METHVIEW.VCX hat man sehr schnellen Zugriff auf diese Methode, wodurch die "natürlichen" Hemmungen der Entwickler, hier zusätzlich zu dokumentieren, etwas abgebaut werden können.

Wiederfinden

Wenn die in den Sourcen abgelegten Kommentare in eine externe Dokumentation übernommen werden sollen, dann müssen sie entweder an bestimmten Stellen abgelegt oder mittels geeigneter Markierungen auffindbar gemacht werden. Die Methode _Dokumentation() ist ein Beispiel für ein festgelegtes "Wo", die folgende Liste von Kommentarmarkierungen ermöglicht ein Auffinden an beliebigen Stellen.

Markierungen beginnen alle mit "*!"

Markierungen im Header:

*!C   <Comment: einzeiliger Kommentar / Beschreibung des Moduls>
im Header jede(r/s) PRG/PROC/FUNC/CLASS sollte 1-2 Zeilen nach *!N stehen
*!DEV <zuständiger Entwickler>  (optional)
*!E   <Beispielaufruf Zeile>
*!>   OPTIONAL: <aus diesem Modul aufgerufenes Modul (Methode/PROC/FUNC)>
*!<   OPTIONAL: <in diesem Modul enthaltenes Modul /Methode/PROC/FUNC)>
*!T   <Laufnummer> :  <zu übergebender Parameter>   <Beschreibung>
*!P   <Property>  <Beschreibung>
*!V   <Variable>  <Beschreibung>
*!K   <Konstante>  <Beschreibung>
*!B   <ggfls. mehrzeilige Beschreibung>
 
*  Historie:
*!#   <Versionsnummer>  / <Datum> <Kommentare>

Der Header endet mit (manchmal ziemlich sinnvolles Lineal):
*--------*---------*---------*---------*---------*---------*---------*

im restlichen Code:

*!D         <Programmdokumentationstext>

Kann automatisiert ausgelesen werden, um technische Dokumentation für Entwickler zu erstellen

*+ alt:  <Erfolgt_Datum>  <Entwickler>  [<Alter Code>]:
[am <Erfolgt_datum> wurde dieser Code auskommentiert.

Hilft Änderungen nachzuvollziehen, besonders, wenn plötzlich Fehler auftreten. Kann / sollte irgendwann später mal gelöscht werden, am besten, wenn die Änderung einige Zeit fehlerfrei gelaufen ist. Der Code bleibt in der Regel da stehen, wo er vorher war. Falls das zu unübersichtlich wird (langer Codeblock), an das Ende der aktuellen Datei verschieben. Anstelle <Alter Code> wird dann z. B.: "siehe:*!#01"]

*!!   <Erfolgt_Datum>  <Entwickler>  <Was muß gemacht werden>

oder

es muß noch etwas geändert/ergänzt/geklärt werden.

*<"normaler", nicht doku-relevanter Programm-Kommentar>

Werkzeuge

Auf dem Markt befinden sich eine Reihe unterschiedlichster Werkzeuge, die helfen können, bei der Dokumentation eigener Programme sehr viel Zeit zu sparen, oder "schöne" bzw. professionelle Dokumentationen ermöglichen.

• Hilfen im/für Quellcode
• CEE - Editor-Erweiterungen, die u.a. komplette Textblöcke in den Code einfügen können (Freeware)
• TextPrint - Druck (Freeware)
• VFP-Dokumentations-Wizzard (Bestandteil von VFP)
• FinePrint - Druckertreiber, der mehrere Seiten auf einem Blatt druckt (Shareware / spart Papier)
• Struktur-Dokumentation
• Rational Rose - Klassenmodelle
• Visual Modeler - Spar-Version von Rational Rose, im Visual Studio Enterprise enthalten

Rational Rose Export Wizard - eine Konverter von/nach RR und Visual Modeler (Download vom MS-Server für registrierte Visual Studio Bsitzer)

• XCase - Datenmodellierung + Dokumentation (ER-Diagramme)
• bidirektionale Schnittstelle zu VFP
• Stonefield Database Toolkit - Daten-Wartung + Dokumentation (Reports)
• PDM - erzeugt HTML-Hilfe zu Klassenstrukturen (Freeware)
• ClassDoc - druckt Klassenstrukturen (Beerware von Sebastian Flucke)
• Power Help - erzeugt ein Hilfesystem basierend auf VFP-Klassenstrukturen

Die Tools sind z.T. auf der Begleit-CD enthalten, ansonsten findet sich dort ein Hinweis auf die Bezugsquelle.

Falls die Zeit reicht werden weitere Tools in der Session gezeigt.