In Zeiten schwergewichtiger Software-Entwicklungsprozesse entstanden massenhafte Dokumentationen, die aber oft zu komplex waren und schnell veralteten. In agilen Projekten ist oft das Gegenteil zu beobachten: Unter dem Motto „Der Code ist die beste Dokumentation“ wird komplett auf jede weitere Beschreibung verzichtet. Dass auch das nicht die richtige Lösung ist, wird spätestens dann klar, wenn ein neuer Mitarbeiter verstehen will, wie die Software aufgebaut ist – und warum sie gerade so und nicht anders strukturiert ist.
Wie eine gelungene Architekturdokumentation aussehen kann, thematisiert Stefan Zörner in seinem neu erschienen Buch Softwarearchitekturen dokumentieren und kommunizieren (Anzeige). Dabei beschreibt er einen praktikablen Weg, der sich gerade auch für agile Projekte eignet. Anstelle umfangreicher Vor- oder Nachdokumentationen schlägt er vor, Architektur und Entwurfsentscheidungen während der Entwicklung mitlaufend zu dokumentieren. Folgt man den Empfehlungen, so entsteht ein übersichtliches Architekturdokument mit höchstens 30 Seiten, das für alle wesentlichen Stakeholder nützlich ist.
Die Empfehlungen werden an einem konkreten Fallbeispiel umgesetzt: Hierzu hat der Autor mit dem System „DokChess“ eine komplette Schach-Engine implementiert. Die im Buch entwickelte Dokumentation steht auf der Website des DokChess-Projekts komplett zur Verfügung – wie auch der Quelltext der Schach-Engine.
Zörner lehnt sich an die Struktur des frei verfügbaren arc42-Templates von Gernot Starke und Peter Hruschka an. Er beginnt mit der Zielsetzung und den Rahmenbedingungen für das zu entwickelnde System. Die Ziele kann man in Form eines Produktkartons dokumentieren, d. h. man überlegt sich, was man auf die Verpackung der Software schreiben würde. Damit erhält man eine prägnante Beschreibung der Eigenschaften und Funktionen des Produkts.
Damit die wesentlichen Architekturentscheidungen später noch nachvollziehbar sind, sollten sie kurz mitsamt den wichtigsten Einflussfaktoren, Annahmen, betrachteten Alternativen und der Begründung für die Auswahl festgehalten werden. Die eigentliche Architektur wird mit Hilfe der folgenden unterschiedlichen Sichten beschrieben: Bausteinsicht inkl. Schnittstellenbeschreibung, Laufzeitsicht und Verteilungssicht. Schließlich sollten auch übergreifende Aspekte fixiert werden, z. B. Schichten-Aufteilung, Gestaltung der Benutzerinteraktion, Persistenz und Sicherheit. Die Dokumentation hilft dabei, diese Themen im gesamten Projekt möglichst einheitlich umzusetzen.
Weitere behandelte Themen sind Werkzeuge zur Dokumentation (wie z. B. UML-Modellierungstools und Wikis), Vorgehensleitfäden sowie mögliche Stolpersteine und wie man damit umgeht.
Fazit: Dieses Buch ist ein Must-Read für alle Software-Architekten und Projektleiter – insbesondere in agilen Projekten. Es hilft, einen praktikablen Weg zu finden, wie man das Wissen über die aufgebaute Architektur erhalten und somit die Zukunftsfähigkeit der entwickelten Software sichern kann.
Zörner, Stefan:
Softwarearchitekturen dokumentieren und kommunizieren
Hanser, München 2012
Das Buch bei amazon (Anzeige)