REDPIXEL - stock.adobe.com
Software optimal warten: Dokumentation und Architektur
Die optimale Wartbarkeit von Software umfasst viele Aspekte der Entwicklung. Dazu gehören eine gute Dokumentation und nachvollziehbare Architekturentscheidungen.
Eine häufige nicht funktionale Anforderung an die Entwicklung neuer Software ist Wartbarkeit. Komplexe Softwareanwendungen sind nie völlig fehlerfrei. Ebenso können sich Anforderungen und Umstände für eine Software im Laufe ihres Lebenszyklus ändern. Nicht zuletzt altert Software. Um all diese Punkte zu berücksichtigen und entsprechend reagieren zu können, werden Softwareanwendungen nach Abschluss des Entwicklungsprojektes oft jahrelang durch ein dediziertes Wartungsteam weiter gepflegt.
Für eine möglichst schnelle Analyse und Behebung von Fehlern sowie die zügige Umsetzung von Änderungen und Aktualisierungen, ist eine gute Wartbarkeit der Software die wichtigste Voraussetzung.
Gute Wartbarkeit umfasst dabei viele Aspekte der Entwicklung, nicht nur die Software selbst. Angefangen bei der Dokumentation über die eigentliche Software bis hin zur Automatisierung soll diese zweiteilige Artikelserie einen kurzen Überblick über die verschiedenen Aspekte geben. In diesem Teil geht es um die notwendige Dokumentation und Architekturentscheidungen. Im zweiten Teil dieser Artikelserie werden der Einfluss von Softwaretests, Codequalität und Automatisierung auf die Wartbarkeit erläutert.
Dokumentation des Softwareprojektes
Der erste Einstieg in eine bestehende Software erfolgt in den meisten Fällen über die vorhandene Dokumentation. Übernimmt ein neues Team die Wartung der Software, muss dieses zunächst verstehen, was die Anwendung fachlich macht und wie sie technisch aufgebaut ist. Für ein bestehendes Team dient die Dokumentation als Nachschlagewerk. Die Dokumentation einer Software umfasst dabei verschiedene Bereiche.
Anforderungen
Im Rahmen der Anforderungsdokumentation müssen die funktionalen und nicht-funktionalen Anforderungen an die Software spezifiziert sein. Dies umfasst im Idealfall mindestens die folgenden Artefakte: Eine Liste der Anwendungsfälle, das erwartete Nutzeraufkommen im produktiven Betrieb, die einzuhaltenden Antwortzeiten des Systems, das erwartete Datenaufkommen im produktiven Betrieb (Mengenbetrachtung) sowie eine Liste der einzuhaltenden Standards und Verordnungen (zum Beispiel BITV 2.0 für Barrierefreiheit).
Architektur
Die Architektur der Software muss klar und verständlich dokumentiert sein. Wichtig ist, dass diese auch aktuell ist. Wenn im Laufe des Entwicklungsprojektes Architekturentscheidungen geändert werden, muss sich dies auch in der Dokumentation widerspiegeln.
Für die Dokumentation von Softwarearchitekturen existieren bewährte Vorlagen, wie zum Beispiel Arc 42. Diese bieten eine vorgegebene Struktur, an der sich Architektinnen orientieren können. Abschnitte der Vorlage, die für die Dokumentation der eigenen Software nicht relevant sind, sollten dabei jedoch nicht gelöscht, sondern mit einem entsprechenden Hinweis versehen werden.
Falls der Einsatz einer solchen Vorlage nicht gewünscht oder möglich ist, sollten in der Architekturdokumentation mindestens die folgenden Artefakte vorhanden sein, um dem Wartungsteam einen möglichst umfassenden Überblick über die Architektur zu vermitteln:
- Kontextdiagramm
- Mindestens eine Bausteinsicht – je nach Komplexität der Software sind auch mehrere Bausteinsichten zur detaillierten Beschreibung einzelner Komponenten sinnvoll
- eine Erläuterung des verwendeten Architekturmusters
- eine Liste der verwendeten Technologien
- eine Auflistung der getroffenen Architekturentscheidungen
- eine Liste der technischen Schulden
- eine Liste aller vorgenommenen Modifikationen von eingesetzten Bibliotheken und Frameworks
Entwicklungsdokumentation
Neben der fachlichen und technischen Dokumentation der Software, sollte auch das Entwicklungsvorgehen dokumentiert werden. Dies hilft dem Wartungsteam, schnell handlungsfähig zu werden und stellt sicher, dass Prozesse und Guidelines, welche in der ursprünglichen Entwicklung vorgegeben wurden, auch weiterhin eingehalten werden.
Die Entwicklungsdokumentation sollte mindestens eine Anleitung zur Einrichtung der Entwicklungsumgebung beinhalten. Im Idealfall gibt es bereits eine fertig eingerichtete virtuelle Maschine (VM), die verteilt werden kann, oder fertige Docker-Dateien, die alle benötigten Komponenten bereitstellen. Fall dies nicht vorhanden ist, sollte eine konkrete Anleitung für die Einrichtung der integrierten Entwicklungsumgebung (IDE) inklusive der verwendeten Entwicklungswerkzeuge (zum Beispiel Tools und Plug-ins) sowie der benötigten Komponenten zur Verfügung stehen.
Neben der der Einrichtung der Entwicklungsumgebung sollte die Entwicklerdokumentation Informationen zu folgenden Themen beinhalten:
- grundlegende Entwicklungsvorgaben
- Code Conventions
- Definition of Done
- Erläuterung des verwendeten Branch-Modells und -prozesses
- Beschreibung des Review-Prozesses
- Anleitungen für Build, Deployment und Release der Software
- eine Beschreibung der Testumgebungen beziehungsweise Stages inklusiver ihrer Konfiguration
Betriebshandbuch
Die Softwaredokumentation sollte ebenfalls ein Betriebshandbuch umfassen. Auch wenn der Betrieb durch den Kunden oder einen anderen Dienstleister erfolgt. Zum einen gehört ein Betriebshandbuch oft sowieso zum Lieferumfang einer Software, zum anderen kann das Wartungsteam das Handbuch nutzen, um den Kunden bei Problemen im Betrieb zu unterstützen.
Folgende Aspekte sollten im Betriebshandbuch aufgeführt werden:
- eine Anleitung zu Installation der Software und für das Deployment neuer Releases oder Updates
- eine Beschreibung der einzelnen Server und Komponenten inklusive der jeweiligen Mindestvoraussetzungen
- eine Liste der anwendungsspezifischen Konfigurationsparameter inklusive einer Beschreibung und erlaubter Werte
- eine Beschreibung, wie das technische und fachliche Monitoring der Software erfolgt
Architekturentscheidungen und Entwicklung
Im Rahmen der Architekturentscheidungen sollte auf einige Punkte geachtet werden, um eine gute Wartbarkeit der Software sicherzustellen.
Einer der wichtigsten Punkte ist die Anzahl der verschiedenen Technologien, die im Projekt eingesetzt werden. Dies betrifft vor allem Microservices-Architekturen. Bei der Entscheidung für oder gegen den Einsatz einer (zusätzlichen) Technologie sollte immer bedacht werden, dass das Wartungsteam in der Regel aus weniger Personen besteht als das Entwicklungsteam. Trotzdem muss das Wartungsteam die gesamte Software verstehen und warten können. Je kürzer die Liste der eingesetzten Technologien ist, desto einfacher hat es später das Wartungsteam.
„Übernimmt ein neues Team die Wartung der Software, muss dieses zunächst verstehen, was die Anwendung fachlich macht und wie sie technisch aufgebaut ist.“
Anja Bethge, adesso SE
Grundsätzlich sollten möglichst keine exotischen Technologien, Frameworks oder Bibliotheken eingesetzt werden. Bekannte, erprobte und vor allem langfristig gepflegte Technologien, Frameworks und Bibliotheken sind zu bevorzugen. Dabei sollten auch stets die neusten Versionen verwendet werden. Sollte der Einsatz einer exotischen Technologie doch einmal notwendig sein, muss dies gut begründet dokumentiert sein.
Ein weiterer wichtiger Faktor für gute Wartbarkeit ist das Logging in einer Software. Die Log-Einträge sind für das Wartungsteam in der Regel der wichtigste Anhaltspunkt für die Analyse von Problemen. Daher ist es notwendig, dass eine Software in ihrem Programmablauf regelmäßig mit Unterstützung verschiedener Log-Level (Debug, Info, Warn, Error) Auskunft über ihren aktuellen Zustand gibt. Zu diesem Zweck sollte ein entsprechendes Logging-Konzept erstellt und von den Entwicklern konsequent umgesetzt werden.
Um Log-Einträge eindeutig einem Prozess auch über mehrere Services und Komponenten hinweg zuordnen zu können, empfiehlt sich der Einsatz von Trace-IDs. Auch zusätzliche Metainformationen wie zum Beispiel die Nutzer-ID oder die loggende Komponente sind wichtige Anhaltspunkte für die Analyse von Fehlern.
„Einer der wichtigsten Punkte ist die Anzahl der verschiedenen Technologien, die im Projekt eingesetzt werden.“
Thilo Lange, adesso SE
Vor allem in Microservices-Architekturen ist es wichtig, dass die Einsicht der Log-Einträge der verschiedenen Services und Komponenten an zentraler Stelle erfolgt. Dies kann durch den Einsatz speziell dafür ausgerichteter Werkzeuge erreicht werden. Im Open-Source-Bereich hat sich hier beispielsweise der ELK-Stack (Elasticsearch, Logstash, Kibana) bewährt.
Im Rahmen der Entwicklung kann jedes einzelne Mitglied des Entwicklungsteam die Wartbarkeit unterstützen, indem es die Prinzipien von Clean Code befolgt.
Fazit und Ausblick
Die Grundlagen für eine gute Wartbarkeit werden bereits zu Beginn eines Entwicklungsprojektes geschaffen, noch bevor die erste Zeile Quellcode geschrieben wird. Die Dokumentation von Anforderungen und Architekturentscheidung sind ebenso wichtig wie die Auswahl der Technologien und das Logging.
Über die Autoren:
Anja Bethge ist Softwarearchitektin bei der adesso SE und spezialisiert auf die Wartung, Pflege und Weiterentwicklung von (Lagacy-) Software. Sie hat umfangreiche Erfahrung in der Transition und langjähren Pflege verschiedenster Softwareprojekte und hat dabei schon viele gute und auch nicht so gute Beispiele für wartbare Software gesehen.
Thilo Lange ist Softwarearchitekt bei der adesso SE und kann mit seiner langjährigen Berufserfahrung auf ein umfangreiches Wissen in der Umsetzung von Webapplikationen mit Java-Backend zurückgreifen. Er hat bereits mehrere Projekte in der Wartung und Pflege übernommen und sich zum Ziel gesetzt, Software so zu entwickeln, dass sie gut wartbar ist und es auch bleibt.
Die Autoren sind für den Inhalt und die Richtigkeit ihrer Beiträge selbst verantwortlich. Die dargelegten Meinungen geben die Ansichten der Autoren wieder.
