Von Pyramiden und (nicht vorhandener) Dokumentation

Inhaltsverzeichnis

Als Cäsar Ägypten besuchte und Kleopatra kennenlernte, waren die Pyramiden bereits über 2000 Jahre alt. Man stelle sich die folgende Unterhaltung zwischen beiden vor. Im Hintergrund die mächtigen Pyramiden, der Himmel tiefblau, die Luft noch frisch. Kurz, ein wunderschöner Morgen im alten Ägypten.

Cäsar: "Beeindruckende Bauwerke. Von wem und wofür wurden die gebaut?"

Kleopatra: "Das weiß ich nicht. Auf jeden Fall entstanden sie vor meiner Geburt."

Cäsar: "Der Bau wurde bestimmt dokumentiert. Ohne Dokumentation können solche Bauwerke nicht entstehen. Das ist viel zu kompliziert. Wo befindet sich euer Langzeitarchiv?"

Kleopatra: "Wir haben eine Bibliothek in Alexandria. Wenn dich die Dokumentation so sehr interessiert, dann sollten wir dort suchen. Alternativ könnten wir auch eine romantische Bootsfahrt auf dem Nil machen?"

Also begeben sich die beiden nach Alexandria, kommen spät am Abend an und beginnen sofort, in der Bibliothek nach Aufzeichnungen zum Bau der Pyramiden zu suchen. Leider finden sie nichts. Es gibt tausende Schriftrollen. Das Ordnungssystem wurde über die Jahre mehrfach geändert und nur lückenhaft auf den Bestand an Aufzeichnungen angewendet. Die Suche bleibt erfolglos.

Allerdings stellt sich Cäsar mit der Fackel "etwas" ungeschickt an und das Unglück nimmt seinen Lauf. Der Rest ist Geschichte, die Bibliothek brennt ab. Falls es dort eine Dokumentation zum Bau der Pyramiden gab, ist sie für immer verloren. Was nun?

Geschichte als Mittel zum Zweck

Wie in vielen anderen fiktiven Geschichten wurde auch hier Bezug auf bekannte Personen, Ereignisse und Bauwerke genommen. Der Einstieg für die Leser ist so auf jeden Fall unterhaltsamer. Der Zugang zum Grundthema hoffentlich auch. Man kennt das von der Geschichte um das trojanische Pferd. Sobald diese besondere Sorte "Pferd" in einem Artikel genannt wird, hat man als Leser oder Leserin bereits ein Gefühl, worum es geht. Besonders dann, wenn es sich um einen IT-Artikel handelt.

An dieser Stelle geht es allerdings um Dokumentation. Das hat die Einleitung vielleicht recht offensichtlich unoffensichtlich verraten. Ein Thema, mit dem man in der IT ständig in Kontakt kommt. Egal ob als Anwender, Entwickler oder in einer anderen Rolle. Und egal, ob man eine Dokumentation liest oder schreibt, das Thema hat viele Facetten: von Zielsetzung, Zeitpunkt und Umfang über Gültigkeit, Zielgruppe und Kontext hin zu Struktur, Budget und Verfügbarkeit. Das alles wurde vermutlich schon tausendfach diskutiert.

Unstrittig dabei ist meist, dass man in bestimmten Situationen dokumentieren sollte. Strittig wiederum die Festlegung der Situationen. Dabei sollte die Dokumentation der jeweiligen Situation und damit den Anforderungen angemessen sein. Dazu kann es nach Erfahrung des Autors nicht die eine Art zu dokumentieren geben. Das liegt in der Natur der Sache. Oder gibt es genau eine Sprache, in der sich Menschen verständigen? Eine einzige Musik, zu der sie tanzen? Oder gar nur ein Nahrungsmittel, von dem sich alle ernähren? Ein Fehler in einer Software ist anders zu dokumentieren als eine Softwarearchitektur. Überraschend ist daher, dass manchmal nur eine einzige Dokumentationsvorlage existiert. Die muss auf alles passen ... oder passend gemacht werden.

Verfügbarkeit, aber wo?

Zurück zur Geschichte von Cäsar und Kleopatra. An diesem Beispiel lässt sich ein Aspekt von Dokumentation besonders schön veranschaulichen: die Verfügbarkeit. Deswegen wurde die Geschichte ja gewählt. Je länger eine Anwendung in Gebrauch ist, desto höher ist die Wahrscheinlichkeit, dass die zugehörige, separat erstellte und gelagerte Dokumentation nicht mehr verfügbar ist. Nicht ganz so überraschend mag da sein, dass damit einhergehend auch oft die dem Design zugrunde liegende Idee verloren geht. Denn Fehler sind zu beheben und neue Funktionen einzubauen. Das ist Wartung.

Entwickler sind sich oft (ganz wie Cäsar in der Geschichte) sicher, eine Dokumentation müsse vorhanden sein. Allerdings ist sie nicht auffindbar. Wahrscheinlich haben so schon viele in ihrem Leben etliche Stunden mit der Suche nach Dokumentation verbracht – wertvolle Zeit.

Wie geht man damit um? Ein Ausgangspunkt kann sein, was für Entwickler (noch) zugänglich ist: die Entwicklungsobjekte, bestehend aus Klassen, Datenbanktabellen und vielem mehr.

Ganz ähnlich wie mit den Pyramiden. Diese sind auch noch da und vermutlich noch auf lange Zeit – selbst wenn die Dokumentation dazu nicht mehr vorhanden ist. Also kann man an den Bauwerken die Antworten auf die Fragen suchen, die einen antreiben. Nachfolgend einige Vergleiche zwischen der Untersuchung von Pyramiden und der Untersuchung von Software.

Mittel der Wahl

Ein erster Ansatz kann die Betrachtung der Pyramiden vor Ort sein. Ganz klassisch: Man notiert seine Eindrücke, vermisst von Hand, prüft die verwendeten Materialien, führt Ausgrabungen durch und vieles andere mehr. In der IT entspricht das einer manuellen Analyse. Man sieht sich die Entwicklungsobjekte in der Entwicklungsumgebung an. Methoden, Klassen und Datenbanktabellen, manchmal sogar Unit-Tests und all die anderen Bausteine einer Anwendung.

Einen weiteren Ansatz bietet moderne Technik. Cäsar hätte darauf zwar nicht zurückgreifen können, aber Drohnen mit hochauflösenden Kameras und Bodenradar können heute schnell neue Erkenntnisse über die Pyramiden und ihre Umgebung liefern. Solche Möglichkeiten bestehen auch für Software. Man kann sich zum Beispiel ein Klassendiagramm generieren lassen. Dadurch erhält man schneller einen Überblick und kann interessante Entwicklungsobjekte und ihre Zusammenhänge identifizieren.

Dann wäre da noch der Ansatz durch Ausprobieren. In Bezug auf die Pyramiden: Gibt es einen antiken Mechanismus, den man heute noch aktivieren kann? Zwar lehrt jeder gute Abenteuerfilm, dass man genau das nicht tun sollte. In der Realität kann die Beobachtung der Funktionsweise aber sehr aufschlussreich sein – wenn man dadurch nur nicht gerade einen uralten Fluch freisetzt. In der Softwareentwicklung bedeutet das, die Software nach Möglichkeit in einer Testumgebung auszuführen. Der Debugger hilft, die Funktionsweise nachzuvollziehen. Daraus kann wiederum ein Laufzeitdiagramm entstehen.

Zu guter Letzt wäre da noch die Dokumentation am oder im zu untersuchenden Objekt selbst. In den Pyramiden gibt es beispielsweise Abbildungen an den Wänden, die aus der Zeit ihrer Entstehung berichten. In Quelltexten gibt es wiederum Kommentare, und manche Entwicklungsobjekte lassen sich sogar separat dokumentieren, wobei die Dokumentation dadurch ein Bestandteil des Entwicklungsobjekts ist. Eine mehr als sinnvolle Einheit, die auch noch Jahre später Aufschluss geben kann.

Das waren nun mehrere Ansätze, die vielen Entwicklern aus ihrem Arbeitsalltag bekannt vorkommen dürften. Alle Ansätze stützen sich dabei auf das, was überdauert: die Entwicklungsobjekte selbst. Im Gegensatz zu einer Dokumentation, die häufig mit einer Textverarbeitung als separate Datei erstellt wird. Durch die fehlende Verbindung zwischen der Dokumentation und den eigentlichen Entwicklungsobjekten, die zur Ausführung der Anwendung notwendig sind, kann das Unglück ungehindert seinen freien Lauf nehmen. Denn es entstehen zwei "Lebenszyklen". Der eine betrifft die Anwendungsobjekte, der andere die Dokumentation. Berücksichtigt man nun noch die in der Praxis häufig unterschiedlichen Ablageorte, ist die fehlende Verfügbarkeit von Dokumentation keine Überraschung mehr, ebenso der zeitlich schnelle Verlust der inhaltlichen Gültigkeit. Eine logische Einheit ist eben keine technische Einheit.

Damit rückt, zumindest für Entwickler, die Bedeutung der Aussagekraft von Entwicklungsobjekten noch stärker in den Vordergrund. Glücklicherweise gibt es für dieses Thema Hilfe: Clean Code. Eine Sammlung von Regeln, Konzepten, Verfahren und einigem anderen mehr, um verständliche und damit wartbare Entwicklungsobjekte zu erzeugen. Auch für die vom Autor verwendete Programmiersprache ABAP (Advanced Business Application Programming) der Firma SAP gibt es seit ungefähr einem Jahr eine an diese Sprache angepasst Umsetzung in Form des "Clean ABAP"-Handbuchs. Es ist öffentlich und jeder kann, dank der Möglichkeiten von GitHub, daran mitarbeiten.

Schlussworte

Die Bewertung nach einem Jahr Arbeit, unter bestmöglicher Berücksichtigung der Empfehlungen aus diesem Handbuch im Arbeitsalltag, fällt mehr als positiv aus. Die Entwicklungsobjekte selbst beantworten nun schon so manche Frage, die früher eine Dokumentation hätte beantworten müssen. Eine Dokumentation wird dadurch zwar nicht obsolet, aber das Fehlen einer Dokumentation wird erträglicher. Das Schreiben einer Dokumentation wird übrigens, dank der Strukturiertheit, die Clean Code einfordert, leichter.

Zum Schluss dieses Artikels noch eine interessante, historische Tatsache: Auch die Erbauer der Pyramiden mussten üben. Zeugnis davon legt heute noch die Knickpyramide ab. Sie entspricht nicht "ganz" der gängigen, geometrischen Vorstellung einer Pyramide. Und auch hier findet sich eine Parallele zu der Arbeit von Entwicklern: Das Programmieren nach Clean-Code-Prinzipien muss geübt werden. Wieder und wieder ...

Michael Keller
arbeitet als Softwareentwickler mit der Programmiersprache ABAP im Logistikumfeld von SAP-ERP-Systemen. Darüber hinaus beschäftigt er sich auch in seiner Freizeit mit dieser Sprache, ist als Blogger in der SAP-Community und als Dozent an einer Fachhochschule tätig.

(ane)