Automatisch erstellte (Struktur-)Dokumentation, lesbarer Quellkode

Hierunter wird verstanden, dass sich aus gut lesbarem Quellkode und verwendeten Datenbanken mit Hilfe von speziell darauf ausgerichteten Programmierrichtlinien und Werkzeugen wesentliche Teile der Dokumentation jederzeit aktuell erzeugen lassen. (Design for Reverse Engineering, Softwarevisualisierung)

Zielsetzungen

• Synchronisation von ausführbarem Programm und Dokumentation (reduziert Irrtümer durch lügende Dokumentation),
• Höhere Transparenz des Quellkodes für den Nutzer – mittelbar über eine IST‑Dokumentation (erleichtert die Aufdeckung logischer Fehler und Inkonsistenzen),
• Integrierte Darstellung der (Struktur der) Geschäftsobjekte und der Geschäftslogik (erleichtert die Kontrolle der Geschäftsregeln, Abhängigkeitsanalysen und Integrationsprojekte),
• Bessere Lesbarkeit des Quellkodes – für Menschen (reduziert Aufwand bzw. Irrtümer beim Einarbeiten in unbekannten Quellkode),
• Leichtere Prüfung und Durchsetzung von umfangreicheren Richtlinien zu Design und Kodierung (erleichtert Einarbeitung neuer Mitarbeiter, verbessert den Truck-Faktor).

Erläuterungen

Alle Aspekte einer Systemdokumentation, die sich im Prinzip aus dem Quellkode oder einer Datenbankstruktur ableiten lassen, sollen auch wirklich aus diesen generiert werden. Anderenfalls entsteht wegen der Duplikation von Information bald das klassische Problem, dass die Dokumentation bezüglich des aktuellen Quellkodes lügt – das Änderungskostenrisiko steigt erheblich.
Allgemeine Werkzeuge zur Quellkodeanalyse bzw. Softwarevisualisierung und Datenbankstrukturanalyse können hier bereits zu einem gewissen Grad helfen. Wichtiger ist jedoch, dass sich mit dedizierten Werkzeugen unterstützt durch geeignete Richtlinien für Programmierung und Benennung wesentlich höhere Abstraktionsstufen der Dokumentation erreichen lassen (bis hin zur graphischen Darstellung auf der Ebene der Geschäftsobjekte und -abläufe). Diese Dokumentation ist dann nicht nur für Programmierer lesbar sondern kann auch von jenen Mitarbeitern beim Nutzer, die mit der inhaltlichen (Weiter‑)Entwicklung des Systems befasst sind, auf inhaltliche und konzeptionelle Probleme überprüft werden. Hierbei kommt der integrierten Darstellung von Geschäftslogik und Speicherung der Geschäftsobjekte in Datenbanken besondere Bedeutung zu – insbesondere auch für zukünftige Integrationsprojekte. D.h. in der erzeugten Dokumentation sollte die Navigation zwischen den Strukturen der (gespeicherten) Geschäftsobjekte und den Teilen der Funktionalität, die diese jeweils nutzen, einfach und präzise möglich sein.

Grundlage für die Lesbarkeit des Quellkodes ist insbesondere, dass sich die Entwickler darüber im Klaren sind, dass der Quellkode in erster Linie für Menschen und nur in zweiter Linie für eine Maschine geschrieben wird. Daher ist es erforderlich, über die maschinelle Analysierbarkeit hinaus einheitliche Richtlinien zur Benennung und Strukturierung des Quellkodes und der Datenbankobjekte festzulegen. Bei der heutigen Unterstützung durch Werkzeuge (u.a. in IDEs) zur Umbenennung von Variablen, Attributen, Methoden, Klassen usw., gibt es keine Rechtfertigung mehr für nichtssagende oder gar irreführende Benennungen. Auch sollte man dem Quellkode nicht gleich ansehen können, welche(r) Mitarbeiter(in) eines Entwicklungsteams ihn geschrieben hat – individuelle Noten sollten sich, wenn unvermeidbar, auf Kommentare beschränken.
Außerdem sollen Entwickler bevor sie einen Kommentar in den Quellkode schreiben sich immer fragen, ob sie die beabsichtigte Information nicht auch durch eine bessere Benennung und Strukturierung des Quellkodes ausdrücken können. Kommentare als Deodorant für Kode geringer Ausdruckskraft müssen vermieden werden.

Beispiele zu Programmierrichtlinien

• Benennung: Für eine Maschine macht es keinen Unterschied, ob eine Variable

  xxx 

  oder

  abteilung 

  heißt – für einen anderen Entwickler schon.
• Ersatz für Strukturierung: Wenn es sich schon nicht vermeiden lässt, dass über die ganze Applikation verteilt SQL‑Statements aus Strings zusammengebaut werden, dann sollten wenigstens alle Variablen, die literale Teile von SQL-Statements enthalten, über eine Namenskonvention erkennbar sein. So wird es z.B. möglich, zwischen einer normalen Aufzählung und einer Liste von Datenbanktabellen zu unterscheiden, um so eine Cross-Referenz erstellen zu können, in welchen Klassen und Methoden auf welche Tabellen zugegriffen wird.

Beispiel zu einer generierten Dokumentation

Die dort skizzierte Dokumentation ließ sich allein aus dem reinen Quellkode erzeugen – ohne einen Rückgriff auf Unit-Tests, die noch weit mehr Informationen liefern können.
Die zentrale Fragestellung in diesem Zusammenhang ist nicht, wie viel Aufwand die Erzeugung einer solchen Dokumentation erfordert, sondern mit welchen Richtlinien man diesen Aufwand minimieren kann.
Diese und die Werkzeuge kann man dann auch in anderen Projekten verwenden.

Qualitätskriterien

Die grundlegenden Regeln zur Dokumentation sind:

• Was? das System funktional leisten soll, steht in den Unit- und Akzeptanztests (automatische Wandlung in Dokumentation),
• Wie? das System dieses leistet, steht im aussagekräftigen, lesbaren Produktivkode (automatische Wandlung in Dokumentation),
• Warum? inhaltliche und technische Entscheidungen so gefällt wurden, wie umgesetzt, muss von Hand im Quellkode (automatische Übernahme in die Dokumentation) oder in getrennten Dokumenten erläutert werden (automatische Einbindung in die generierte Dokumentation).

Von diesen Regeln wird es in der Praxis Abweichungen geben. Die Lesbarkeit des Quellkodes ist jedoch ein wichtiges Qualitätskriterium und die Qualität der Dokumentation bemisst sich neben ihrer Vollständigkeit daran, in welchem Maße Duplikation (auch mit Quellkode und Datenbankstrukturen) vermieden werden konnte.

Technische Hinweise, Referenzen

Die folgenden Referenzen stellen kein Qualitätsurteil dar. Sie sollen nur einen ersten Einstieg in Aspekte der Materie bieten.
Diese Anforderung stellt eine Kombination aus verschiedenen Best Practices und Techniken dar, wie Programmierrichtlinien, Reverse Engineering und Round-Trip-Engineering.
Die konkreten Werkzeuge zur Analyse des eigenen Quellkodes und der Datenbankobjekte anhand der darin befolgten Richtlinien müssen natürlich vom Anbieter selbst geschrieben werden. Sie lassen sich jedoch recht einfach gestalten, weil er die Richtlinien ja selbst mit dem Ziel der Analysierbarkeit festlegen kann, und sie lassen sich dann i.d.R. auch weitgehend für andere Projekte wiederverwenden.
Ein Ziel dieser Richtlinien ist es demnach, dass sie eine programmiersprachenunabhängige Analyse des Quellkodes ermöglichen. Eine sprachenunabhängige reine Textanalyse sollte möglichst ausreichend sein, um alle gewünschten inhaltlichen und strukturellen Eigenschaften zu ermitteln. Diese Richtlinien können sich auf den Quellkode und die Datenbankobjekte selber und/oder Kommentare (z.B. Javadoc) und Annotationen (z.B. XDoclet) beziehen.
Zur Unterstützung von Analysen, der Softwarevisualisierung und der Dokumentationsaufbereitung gibt es unzählige Werkzeuge für die unterschiedlichsten Aufgaben. Erwähnt sei hier nur Checkstyle für die automatische Überprüfung von Richtlinien. Für die Ausgabe der Datenbankstrukturen und –kommentare als Textdateien stellen die Datenbanken selbst i.d.R. Werkzeuge oder Schnittstellen bereit.