Dokumentation von Software Projekten ist ein echtes Stiefkind der Branche. Ein altes Sprichwort sagt, dass auch bei vorhandener Dokumentation sich 90% auf eine veraltete Version beziehen und teils ungültig sind, und von den den restlichen 10% sind wiederum 90% unverständlich. Vielfach lassen Programmierer daher nur den echten Code als sich-selbst erklärende und exakte aktuelle Dokumentation gelten.

Es der Gemengelage gab und gibt es im wesentliche zwei Trends. Da ist zum einen, das Verhältnis von Code und Doku umzukehren, also hauptsächlich Text zu schreiben, und darin eingebetteten Code zu haben. Dieses hat sich zwar für Quelldateien nicht durchgesetzt, aber die Idee findet sich in zwei Bereichen wieder: zum einen das Wiederaufleben von "verständlichen" Programmiersprache (anstatt einer Universalsprache für alle Projektteile), darunter auch SQL und XCode. Zum anderen die Verwendung von UML Diagrammen mit angebundenen Codestücken, was jedoch die Renovierung von Programmen behindert.

Der zweite Trend ist die Generierung von Dokumentation aus jedwedem Quellcode. Am bekanntesten sind da natürlich die Javadoc/NDoc/Doc++ Werkzeuge, die die Funktionsparameter zusammen mit Code-begleitenden Kommentaren auslesen und übersichtlich aufbereiten - im wesentlichen den eigentlichen Code entfernen und querverlinkte Index-listen bilden. Dies reicht oft schon, um die Ausführungsbeziehung zweier Klassen zu klären, und wenn es irgendwo noch ein längeres Beispiel zu Varianten über mehrere Funktionsrufe hinweg gibt, dann umso besser.

Spezialisierung

Damit ist aber auch noch nicht abgedeckt, wenn objekt-übergreifende Beziehungen zu betrachten sind, was insbesonders wichtig ist Software renoviert werden muss. So stellt sich etwa heraus, dass viele Projekte anhand von kaum formalisierten Schemata errichtet wurden. Am bekanntesten sind da wohl einge Widget-Kits, Gtk implementiert ein Objekt-Modell in blankem C, Qt implementiert ein Signal-Slot-Modell, und MFC besitzt ein unterliegendes DDX Protokoll zur Bindung. Viele liefern hier spezialisierte Doc-Werkzeuge mit, die diese Strukturen zusätzlich mit-dokumentieren.

Für die eigenen Software im Hause gibt es das nicht, und es stellt sich oft als eine hohe Hürde heraus, sich selbst Werkzeuge zu schreiben, die typische Spezialitäten erkennen und dokumentieren. Im Laufe der Zeit habe ich für meine eigenen Projekte jeweils Werkzeuge geschrieben, die "sinnvolle" Dokumentation erzeugen, wie ich sie gerade brauchte. Letztlich, habe ich mir einen Fundus angelegt, und versucht, diese für Wiederverwendung aufzubereiten.

Projekte

Tatsächlich ist es gar nicht so schwierig, sich angepasste Dokumentations-Werkzeuge zu schreiben. Vielfach gibt es ein bestimmtes Interesse an einer typischen Struktur, und man durchsucht einfach seine Programmbestände eben danach. Wo es falsche Treffer gibt, da verändert man kurzerhand die Quelltexte, und man bekommt so eine aktuelle und korrekte Liste, die man aufbereitet. Nahezu alle Softwareprojekte haben entsprechenden Skripte enthalten, die ich hier nicht aufzählen will - aber sie geben mir einen reichen Erfahrungshintergrund.

Eine weitere Möglichkeit ergibt sich durch Erweiterung eines Standardwerkzeugs für Dokumentation. Das ist leichter gesagt als getan - wenn es überhaupt ein Modulkonzept gibt (oder alternativ ein verständlicher Quellcode des Werkzeugs vorliegt), so muss man sich da jeweils einarbeiten, und das nächste Projekt braucht wieder ein anderes Werkzeug. Die meisten der bereitgestellten Modulkonzepte sind auch in erster Linie dazu gedacht, Anpassungen der Ausgabeformatierung vorzunehmen, und eben nicht mehr Informationen aus der Eingabe herauszulesen und zu verarbeiten.

Da gibt es zwei Wege: zum einen habe ich mir selbst Projekte für Dok-Prozessoren geschaffen, die einen Standardsatz an Funktionalität bereitstellen, und die leicht erweiterbar sind. Eines der späteren und größeren ist dabei das XM-Tool, das in Perl geschrieben ist, und auf die Mischung aus C und Forth Code des PFE Projektes angewendet wurde. Dieses liess sich auch für anderen Projete adaptieren.

Der Name gewinnt sich aus einer anderen Beobachtung: dass es notwendig ist, sowohl für den Hauptprozessor als auch für Erweiterung ein einheitliches Datenformat zu verwenden, wofür sich XML am besten eignet. Dieses habe ich in anderer Variante später noch einmal angesetzt, indem ich aus dem eigentlich für Datenbanken gedachten XML AST/TA-Modell einen optimierten Dok-Prozessor errichtete. Dazu wurde dann auch ein universitäres Paper aufgesetzt, da jedoch die Vergleichsobjekte an Doc-Prozessoren so sehr verschieden implementiert sind, blieb die Stichhaltigkeit nicht mehr zwingend nachzuweisen, dass das XML-basierte AST/TA-Modell hier bestens ist.

In späterer Zeit gesellten sich dann dritte Methoden hinzu, denn die klassischen Doc-Prozessoren erlernten irgendwann, ihre Ausgabe oder sogar Zwischenstände in XML auszugeben. Nunmehr war es mir möglich, eigene Werkzeuge mit XML-Basis einzusetzen, und nicht nur den blanken Quellcode als Eingabe zu nehmen, sondern auch die schon erfassten Zusätze andere Prozessoren zu vereinnahmen. Spätestens mit der Einführung von colorgcc in den letzten GCC Versionen ergeben sich hier neue Möglichkeiten, da man nun nicht mehr selbst die Grundroutinenen schreiben muss, die Standardcode verstehen müssen.

Program Transformation

Hier sei noch eine weitergehende Information untergebracht: das Verstehen von Code durch automatisierte Werkzeuge ist nicht nur zur Dokumenation wichtig, die zur Verwendung in neuen Projekten gebraucht wird. Man kann damit auch die Renovierung von Software befördern. Je besser aber Code von Werkzeugen verstanden wird, umso besser kann man sogar Quellcode automatisiert umsetzen - zum Beispiel von einer veralteten Programmiersprache, Plattform oder Widget-Kit in eine modernere Variante. Dieses Feld nennt sich allgmein "Program Transformation".

Die Program Transformation und ausgereifte Software habe ein paar Gemeinsamkeiten: sie beinhalten eine Parser-Phase und Analyse-Phase zum Verstehen der vorhandenen Beständen, und eine Rekombinations-Phase und Transformations-Phase um erweiterte Formen zu finden. Ein zentrales Element ist dabei der Begriff des "Pattern"s, die man trotz Variantenreichtum immer erkennen möchte.

Hier kann man dann noch ein Projekt hinzuzählen, der in der Diplomarbeit zur Schema-Transformation von Datenbanken zu finden ist. Dieser enthält einen selbstgeschriebenen SQL-Eingabeparser, während intern eine semistrukturierte XML-Datenbasis aufgebaut wird. Dieser versteht sowohl die DDL für die Schemabeschreibung, als auch eine DML-Variante zur Beschreibung von Regeln zur Schemaveränderung. Das Aufstellen von Code zum Verstehen des unterliegenden datenbank-orientierten Modells ist hier sehr ausgeprägt.