Kolumne: Stropek as a Service

Pflicht und Kür: Dokumentation als wichtiger Faktor für langfristigen Erfolg von Software
Keine Kommentare

In den letzten Monaten hatte ich Beratungsengagements in mehreren Projekten, bei denen es um die Analyse bestehender Softwarelösungen ging. Ein Projekt war eine Cloud-basierte SaaS-Lösung, ein zweites stand am Beginn der Transformation in Richtung SaaS und ein drittes war eine klassische Individualsoftware für den Betrieb im eigenen Rechenzentrum. In allen Fällen war es meine Aufgabe, die bestehenden Softwaresysteme hinsichtlich ihrer Architektur zu analysieren und Aussagen über Stärken, Schwächen und dringend notwendige Investitionen zu machen.

Auch wenn die Softwaresysteme aus komplett unterschiedlichen Domänen kamen, hatten meine Analyseergebnisse etwas gemeinsam: den Hinweis auf klaffende Lücken im Bereich Dokumentation. Ich fühlte mich am Ende der Projekte zugegebenermaßen nicht ganz wohl, da ich normalerweise alles andere als ein Dokumentationsfanatiker bin. Getreu dem Agilen Manifest werte ich funktionierende Software höher als umfassende Dokumentation. In Codereviews bin ich der Letzte, der auf Kennzahlen wie Anzahl der Kommentarzeilen im Verhältnis zu Lines of Code herumreitet. Seit Jahren predige ich, dass das Wasserfallmodell und Big Design Up Front sehr schlecht funktionieren und fast immer ineffizient sind. Trotzdem verwendete ich in den erwähnten Reviewprojekten einen großen Teil meiner Zeit darauf, die Wichtigkeit von Architektur-, Design- und Codedokumentation zu unterstreichen. In dieser Ausgabe meiner Kolumne möchte ich erklären, warum.

Detaildokumentation

Ein Team, das guten Code schreibt, sollte meiner Meinung nach nicht viel Zeit damit verbringen, zu dokumentieren, wie eine Software im Detail funktioniert. Wenn

  • Namen von Modulen, Klassen, Funktionen, Variablen etc. gut gewählt sind,
  • der Code gut strukturiert ist,
  • Unittests die Anforderungen implizit festhalten und sogar automatisch prüfen,
  • DevOps-Prozesse automatisiert sind
  • und eine moderne Plattform für Quellcodeverwaltung mit integriertem Anforderungsmanagement (z. B. GitHub, Visual Studio Team Services) genutzt wird,

können die Details, wie eine Softwarelösung funktioniert, auch trotz ganz wenig Dokumentation herausgefunden werden. Hinweise sind nur dort notwendig, wo besonders trickreiche oder nicht offensichtliche Lösungswege gegangen wurden. Falls in einem Projekt eklatante Schwächen bei einem der oben genannten Punkte festgestellt werden, investiert man Zeit und Geld besser darin, diese Schwächen auszumerzen als darin, den schlechten Code zu dokumentieren.

Den Wald vor lauter Bäumen nicht mehr sehen

Dokumentation ist meiner Ansicht nach unverzichtbar, wenn es um die konzeptionelle Ebene geht. Es ist schwierig und frustrierend, die großen Zusammenhänge in einer Softwarelösung aus dem Code herauszulesen. Hier ist begleitende Dokumentation unumgänglich. Die Bedeutung guter, konzeptioneller Dokumentation nimmt bei modernen Cloud-Lösungen sogar noch zu. Sie werden heute in der Regel nach dem Microservices-Architekturmuster gestaltet. Ein Softwaresystem besteht dabei aus vielen lose gekoppelten Teilen, die oft mit unterschiedlichen Technologien entwickelt werden. Das Gesamtbild ist daher schwierig zu erfassen, wenn die zugrundeliegenden Architektur- und Designkonzepte nicht beschrieben sind. Auch gängige Tools, die größere Codebasen analysieren und die Zusammenhänge visualisieren, stoßen meist an ihre Grenzen. Sie sind gut auf einen Microservice anwendbar, aber nur von geringem Nutzen bezüglich des Gesamtsystems.

Mein wichtigster Tipp in Sachen Dokumentation lautet daher, in konzeptionelle Dokumentation zu investieren, statt Details zu beschreiben, die eigentlich nur eine Wiederholung des Quellcodes sind.

Softwareentwicklung ohne Architektur und Design

Eigentlich ist es verwunderlich, dass so viele Projekte keine oder mangelhafte konzeptionelle Dokumentation haben. Die Softwarearchitektur, also die fundamentalen Prinzipien und Zusammenhänge in einem Softwaresystem, ändert sich im Gegensatz zu den Implementationsdetails nicht laufend. Gemäß Wikipedia repräsentiert die Softwarearchitektur „die frühesten Softwaredesign-Entscheidungen. […] Eine einmal eingerichtete Softwarearchitektur ist später nur mit hohem Aufwand abänderbar. Die Entscheidung über ihr Design ist somit einer der kritischsten und wichtigsten Punkte im Entwicklungsprozess einer Software“.

Der Entwurf der Softwarearchitektur sollte also am Beginn eines Projekts stehen, und diesem Prozess sollte entsprechende Aufmerksamkeit geschenkt werden. Wie kann es dann sein, dass in einem Projekt keine Dokumentation der Softwarearchitektur existiert? Hier vier exemplarische Gründe aus meiner praktischen Erfahrung:

  • Die Konzepte existieren nur im Kopf eines kleinen Kernteams, vielleicht sogar von nur einer Person. Für das Niederschreiben hat man weder Zeit noch Lust.
  • Es gibt niemanden (mehr), der die Architektur versteht. Diese Situation sehe ich oft bei in die Jahre gekommenen Softwarelösungen. Gewachsene Strukturen und Personalfluktuation haben dazu geführt, dass man nach der Wildwestmethode ohne großen Plan bei Anforderungen und Problemen aus der Hüfte schießt.
  • Man war der Meinung, dass kein initialer Architekturentwurf notwendig ist. Schließlich entwickelt man agil und arbeitet von Iteration zu Iteration. Ich halte das für einen Trugschluss. Keine Frage, gute Softwarearchitektur kann man agil entwickeln. Sie ist aber kein Nebenprodukt, das automatisch entsteht, nur weil man in einem agilen Prozess arbeitet. Programmieren ohne Softwarearchitektur ist wie das Übereinandersetzen von Ziegeln, ohne sich vorher einen Bauplan für das Haus überlegt zu haben, das man bauen will.
  • Die Spezifikationen werden als Ersatz für die Architekturdokumentation gesehen. Das halte ich speziell bei lange in Betrieb befindlichen Lösungen für problematisch. Das Verstehen einer Systemarchitektur ähnelt in diesem Fall der Archäologie. Man arbeitet sich chronologisch durch die Spezifikationen von Teilprojekten, die über viele Jahre umgesetzt wurden, um ein Verständnis für den aktuellen Aufbau einer Software zu bekommen.

Wie macht man es richtig?

Ich gebe Entwicklungsteams folgende grundlegende Tipps, wenn es um Dokumentation geht:

  • Der Code selbst, inklusive der automatisierten Tests, wird zur Dokumentation der Implementierungsdetails.
  • Zum Code werden Kommentare hinzugefügt, um nicht offensichtliche Besonderheiten zu erklären.
  • Um die Codedokumentation leichter zugänglich zu machen, verwendet man Tools, die aus dem Code eine leicht zugängliche Dokumentationswebsite erstellen (z. B. DocFX, Swagger Tools für Web APIs oder Dokumentationsgeneratoren für Datenbanken wie Redgate SQL Doc). Die Aktualisierung der Dokumentationswebsite ist in die CI/CD-Prozesse integriert.
  • Die Softwarearchitektur ist am Beginn des Projekts schriftlich zu dokumentieren. Indem man sich dazu zwingt, sie für Außenstehende nachvollziehbar niederzuschreiben, steigert man ihre Qualität, da viele Schwächen und Inkonsistenzen im Rahmen dieses Prozesses offensichtlich werden.
  • Als Dokumentationsformat für konzeptionelle Dokumentation empfehle ich Markdown-Dateien, mit denen genauso umgegangen wird, wie mit Quellcode (z. B. Versionsverwaltung, Reviewprozesse beispielweise über Pull-Requests, Qualitätskontrolle mit Markdown Linter, Assoziieren von Änderungen mit Work Items, CI/CD-Prozesse zur Integration in die Dokumentationswebsite). Für Markdown gibt es eine Menge Komponenten, mit denen Zusammenhänge auch grafisch beschrieben werden können (z. B. mermaid).
  • Die Architekturdokumentation wird kurz und prägnant gehalten, indem keine allgemein bekannten Konzepte (z. B. Designpatterns) wiederholt werden. Sie verweist dafür auf externe Ressourcen.
  • Bei der Architekturdokumentation wird genau wie im Code darauf geachtet, dass die Ubiquitous Language der jeweiligen Domäne konsistent verwendet wird.
  • Bei der Spezifikation von Teilprojekten werden Auswirkungen auf und der Zusammenhang mit der Softwarearchitektur vorab beschrieben. Im Rahmen der Implementierung wird die Architekturdokumentation aktualisiert. Das Aktualisieren der konzeptionellen Dokumentation ist fixer Bestandteil der Definition-of-Done-Checkliste des Entwicklungsteams.
  • Wenn neue Mitglieder ins Entwicklungsteam dazustoßen, bittet man sie, sich als Erstes anhand der Dokumentation in das Softwaresystem einzuarbeiten. Ihr Feedback ist besonders wichtig, um Schwächen und Lücken in der Dokumentation aufzudecken.

Dokumentation im Projektalltag

Es ist nicht schwer, Zustimmung zu der Aussage zu bekommen, dass mangelnde Architekturentwicklung und -dokumentation schlecht sind. In der Praxis ist es aber eine Herausforderung, beides konsequent in den Projektalltag einzubinden. Der Wert von Dokumentation ist nicht kurzfristig ersichtlich. Die Anwender spenden keinen Applaus, wenn man mehr Ressourcen pro Arbeitsaufgabe einplant, um die entsprechenden Softwareänderungen sauber in das Architekturdesign einzubetten und die Konzepte entsprechend zu dokumentieren. Die Nachteile, die entstehen, wenn man darauf verzichtet, zeigen sich erst viel später, wenn einem die Kosten für die Wartung und Erweiterung eines Softwaresystems über den Kopf wachsen oder neue Teammitglieder eine gefühlte Ewigkeit brauchen, um sich einzuarbeiten. Es ist unsere Aufgabe als Softwareexpertinnen und -experten, die richtige Balance aus Aufwand und Nutzen von Dokumentation zu finden. Dokumentation darf nicht zu einem Selbstzweck werden. Keine Dokumentation zu haben, ist jedoch auch unverantwortlich.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu:
X
- Gib Deinen Standort ein -
- or -