Wissen fürs Projekt oder für die Schublade?

Software-Design-Dokumente

Berthold Schulte

Software Design Descriptions/Documents (SDD) [1] sind für die erfolgreiche Entwicklung und Wartung von Software unentbehrlich. Wirklich? Wer oder was beeinflusst deren Sinn und Einsatz im Projekt? Was ist eigentlich zu beachten, damit sie nicht schon während des Projekts zum Papiertiger werden und einen Nutzen darstellen können? Eine pragmatische Übersicht.

Ein Dokument dient der schriftlichen Vermittlung von Information und Wissen zwischen Menschen. Software-Design-Dokumente beinhalten im Speziellen das Wissen über eine abstrakte Lösung zum Aufbau eines Stücks Software. Die darin dargestellte Information ist allerdings nur einer sehr kleinen Leserschaft zugänglich – da Wissen aus dem Bereich der Softwareentwicklung noch nicht zum Allgemeinwissen gehört, technisch komplex ist und eine eigene Sprache besitzt.

Die Zielgruppen

Wer gehört zu dieser Leserschaft, welche Erwartungen hat sie und welchen Einfluss hat sie auf das Dokument? Neben den Softwareentwicklern sind Tester, Requirement Engineers, Businessanalysten (BA) sowie der Kunde, die Projektleitung und die IT-Abteilung potenzielle Leser, wenn auch mit einem unterschiedlichen Fokus auf das, was sie aus dem Dokument erfahren wollen.

Softwareentwickler und Dev-Peers: Ein Softwareentwickler hat in der Regel die „engste“ Beziehung zu einem SDD. Einerseits erstellen Softwareentwickler das Design und die Dokumente oft selbst, andererseits arbeiten sie aktiv und ständig damit, da es ihre Arbeitsvorlage ist. Eben diese direkte Beteiligung an der Umsetzung verpflichtet den Entwickler auch zur Wahrung der Aktualität des SDDs. Hält er Änderungen am Design für nötig oder ergeben sich zwingend Gründe dafür, muss er sie in irgendeiner Form niederschreiben. Ansonsten gehen diese Änderungen in der Menge des Codes unter. Arbeitet er mit einem SDD eines zum Beispiel erfahreneren Entwicklers, so muss eine gute und ständige Kommunikation zwischen beiden herrschen. Der Autor des Designs muss auch bereit sein, Änderungen in sein Design aufzunehmen. Diese Art der Kommunikation und aktiven Arbeit mit dem SDD gewährleistet erst die erfolgreiche Dokumentation von Softwaresystemen, die langfristig wartbar sind.

Qualitätssicherung: Tester arbeiten eher passiv mit einem SDD. Ein SDD enthält für einen Tester die ersten Hinweise zum technischen Hintergrund dessen, was er testet. Für reine Blackbox-Tests eines grafischen User Interfaces mag dies nicht weiter relevant sein. Für die Erstellung von umfangreichen Systemtests, die eine Komponente und ihr Zusammenspiel mit anderen Komponenten eines Systems testen sollen, allerdings schon. So können in dem SDD unter anderem die Verbindungen und Abhängigkeiten zu anderen Systemen beschrieben sein, die bei der Testabdeckung und -erstellung auch mitbedacht werden können.

Requirements Engineer: Dem Requirements Engineer vermittelt das SDD einen ersten Eindruck von der zukünftigen Realisierung und Komplexität eines Stücks Software, einer Komponente oder eines ganzen Systems. Er wird je nach Umfang und Detaillierungsgrad des SDD Teile des Systemkontextes, des Datenmodells sowie die wesentlichen Geschäftsabläufe dort wiederfinden und Abweichungen zu seinen Anforderungen feststellen können. Zum Beispiel während eines Reviews gemeinsam mit dem Autor des Designdokuments.

Fachabteilung, Analyst: Der BA wird der erste sein, der das Dokument nur mit fachlichem Background betrachtet. Ihn werden technische Details ebenso wenig interessieren, wie der Zusammenhang im Systemkontext. Ein Blick sowohl in die Zusammenfassung am Anfang des Dokuments und in das Datenmodell als auch in die Anmerkungen zu möglichen Tests und fachlichen Einschränkungen stehen für ihn eher im Vordergrund. Das Umreißen der Anforderungen durch einen anderen Autor und dies in anderen Worten, wird daher für den BA der größte Nutzen aus dem SDD sein können.

Projektleitung, Management, Kunde: Der Projektleitung oder auch dem Kunden gibt das SDD einen Einblick in die Komplexität des Systems und ermöglicht unter Umständen Schlussfolgerungen für den weiteren Projektverlauf und für weitere Timelines. Die IT-Abteilung des Kunden wird ebenso Interesse bekunden, zum Beispiel um zu erfahren, welche weiteren Systeme die zukünftige Software benötigt. Für die Unternehmensführung steht die Begutachtung von SDD sicherlich nicht im Fokus. Allerdings wird in kleineren Unternehmen vom Management gerne mal ein Blick in die laufende Projekte geworfen. Insbesondere wenn die Designphase lange dauert, wirken konkrete Ergebnisse in Schrift und Form beruhigend auf die Geschäftsführung.

Einflüsse von Vorgehensmodellen

Das Vorgehensmodell gibt den Plan vor, wie und in welchen Phasen die Beteiligten zusammenarbeiten. Es unterteilt den Entwicklungsprozess dabei zeitlich und inhaltlich in Phasen, die mehr oder weniger voneinander abgegrenzt sind. Diese Trennung wird dabei je nach Modell entweder forciert oder abgelehnt. Eine sehr ausgeprägte Abgrenzung der Entwicklungsphasen gibt beispielsweise das Wasserfallmodell vor, wohingegen agile Ansätze eher auf einen dynamischen Prozess mit sich wiederholenden Iterationen setzen. Das Vorgehensmodell prägt aber nicht nur die Zusammenarbeit während des Entwicklungsprozesses, sondern auch die Ausgestaltung des SDD und den Sinn und Zweck, den das SDD während der Entwicklung einnehmen kann.

Wasserfallmodell: Bei diesem Vorgehen wird dem Erstellen des Designs und damit dem Schreiben des SDD eine eigene, zeitlich begrenzte Phase nach der Analyse und vor der Implementierung zugeordnet. Danach wird das SDD nur noch während der Implementierung abgearbeitet. Die Designphase ist dabei ein Übergang von kundengetriebenen, fachlichen Aussagen in der Analysephase zu entwicklergetriebenem, technischem Verständnis in der Implementierungsphase. Da dieser Ablauf in der Theorie streng sequenziell ist, muss das SDD als Übergangsdokument wasserdicht sein und darf nicht zu Fragen oder Ungereimtheiten in der darauffolgenden Phase führen. Das heißt, das Dokument muss komplett und exakt sein. Ansonsten landet man, ähnlich der Abfahrt mit der Wasserbahn auf dem Jahrmarkt, im kalten Wasser. Ein Vorgehen nach dem Wasserfallmodell benötigt daher die ausgefeiltesten und umfangreichsten SDD im Vergleich zu den folgenden Modellen.

Iterative Modelle: Bei iterativen Modellen werden die einzelnen Arbeitsschritte, wie zum Beispiel Analyse, Design, Test und Deployment, mehrmals durchlaufen und die Software sukzessive erstellt. Die Schritte sind dabei angelehnt an die Phasen des Wasserfallmodells. Insbesondere liegt das Design zeitlich immer zwischen einem Analyse- und einem Implementierungsabschnitt. Somit wird sich die Designbeschreibung Schritt für Schritt mitentwickeln müssen, wobei die vorherige Version des SDD nicht als komplett angesehen werden muss.

Agile Vorgehensweise: Den wohl am schwersten zu beherrschenden Einfluss üben agile Ansätze aus. Sie setzen eher auf den lauffähigen Code als auf ausgefeilte Designdokumentationen. Daher wird auf die Erstellung einer Designdokumentation gerne explizit verzichtet. Eine Begründung lautet oft: „Der Code ist die Dokumentation und die Anforderungen ändern sich so schnell und oft, dass die Anfertigung und Aktualisierung detaillierter Designdokumentationen den Aufwand nicht rechtfertigt.“ Die Qualität des Codes und das letztendliche Softwaredesign sollen sich bei diesen Ansätzen durch ständiges Refaktorisieren ergeben. Was leider dazu führen kann, dass der Überblick für das Ganze verloren geht und einige Designentscheidungen nicht mehr oder nur bruchstückweise nachvollziehbar sind.

Kosten und Nutzen

Bei wasserfallartigen oder iterativen Vorgehensmodellen ist, wie beschrieben, eine eigene Phase für das Designen und damit das Erstellen eines SDD vorgesehen. Der Umfang und die Länge der Projektabschnitte müssen geplant und ihr Aufwand geschätzt werden. Man hat damit einen guten Überblick über die zu erwartenden Kosten für die Designphase(n), da diese beim initialen Erstellen des Designs und dessen Dokumentation anfallen. Läuft das Projekt aus dem Zeitplan und sind umfangreiche Änderungen nötig, hängt es natürlich von dem dann geplanten Vorgehen ab, welche Kosten entstehen. Hier übertragen sich sowohl die Vor- als auch die Nachteile des jeweiligen Modells auf das SDD. Generell gilt: Je unflexibler ein Vorgehensmodell ist und Phasen strikt voneinander trennt, desto stabiler ist in der Theorie auch das SDD. Die Kosten für Anpassungen des Dokumentes sind gleich Null, da sie im Modell nicht vorgesehen sind? Demgegenüber entstehen bei sehr flexiblen, agilen Vorgehen erst gar keine Kosten für das SDD, weil dessen Erstellung gar nicht vorgesehen ist?

Unter der Annahme, dass auch bei agilen Methoden Designbeschreibungen [2] entstehen und dokumentiert werden, können und sollten Sie die Zeiten, die für das Designen, dessen Dokumentation und das Einpflegen von Änderungen benötigt werden, erfassen und in Abständen von ein paar Tagen oder Wochen auswerten. Wird das Designen und Dokumentieren zu sehr geliebt und besteht beispielsweise die Gefahr von Over-Engineering, sind Anpassungen im Vorgehen immer noch möglich. Wohingegen ein weitergehender Nutzen, von SDD neben der letztendlichen Spezifikation auf Papier, nur schwer messbar ist, aber durchaus gegeben sein kann.

Reflexion: Das Erstellen und Dokumentieren des Designs hat zweierlei „reinigende“ Wirkungen. Zum einen reflektiert der Autor des Dokuments während des Aufschreibens die Ideen und damit das Design noch einmal. Zum anderen können weitere Personen einen Einblick in die Vorstellung vom Design erhalten und ihre Erfahrung miteinbringen. So werden zum Beispiel Design-Patterns gerne zu oft angewendet und unter Umständen auch noch falsch. In einem vom Entwickler erstellten Diagramm lassen sich sowohl dessen Intention im Vorfeld erkennen und so Missverständnisse aufdecken, als auch Wissen und Erfahrung teilen. Bei richtiger und sinnvoller Anwendung solcher Patterns und dem Austausch von Erfahrung können andere Entwickler ebenso davon profitieren. Und dies ohne eine teure Schulung besuchen zu müssen.

Antizipation von Bugs: Kann ein SDD zukünftige Bugs im System antizipieren? Fehler bezüglich der Umsetzung der Anforderungen resultieren oft aus falsch erfassten oder verstandenen Anforderungen und gesetzten Schwerpunkten bei der Entwicklung. Da solche Fehler in frühen Phasen des SDLC günstigster zu beheben sind als in späten, dient ein SDD immer auch der Verifizierung des Geforderten. Oft werden fachliche Ungereimtheiten und Abhängigkeiten erst bei der genauen technischen Ausgestaltung sichtbar, da das Wesen der Implementierung maximale Exaktheit voraussetzt. Zudem dient das Niederschreiben der Entscheidungsfindung für bestimmte Problemlösungen der späteren Nachvollziehbarkeit und deckt kommende technische Problem oft erst auf. So können fehlende, nicht funktionale Anforderungen (NFA), zum Beispiel Schätzungen des zu erwartenden Datenaufkommens oder der Systemlast, zu Designfehlern führen. Das heißt, werden die NFA beim Design der Software nicht berücksichtigt, führt dies später im Betrieb der Software oft zu bösen Überraschungen.

Weisen Sie daher auf fehlende oder ungenaue Requirements im SDD hin, deren Klärung eine exakte technische Umsetzung erst ermöglichen. Und dokumentieren Sie die zu dem Zeitpunkt gemachten Annahmen zur Umsetzung der Lücken. Sie sichern sich als Dienstleister oder Zulieferer damit unter Umständen besser ab, wenn das SDD Teil des Werksvertrages wird und es zu Unstimmigkeiten mit dem Auftraggeber kommen sollte.

Umfang und Ausprägungen

Die Spanne der Ausprägung von Designbeschreibungen kann von losen Skizzen und Diagrammen als Diskussionsgrundlage, bis hin zu ausgefeilten Konzepten und 100-seitigen Spezifikationen als Anleitung zur Implementierung einer Software reichen.

Diskussionsgrundlage: Die Skizze auf Papier oder einem Whiteboard [3] dient natürlich nur als Diskussionsgrundlage, um mit Kollegen über einen oder mehrere Designansätze zu sprechen. Hier stehen eher der kreative Findungsprozess im Vordergrund und dessen mehr oder weniger formale Notation. Zudem bekommen Sie einen ersten Eindruck von der zukünftigen technischen Komplexität des Systems oder der Komponente. Sie können Vor- und Nachteile abwägen, notieren und in einem nachfolgenden ausgearbeiteten SDD aufführen. Ein Leser wird es Ihnen danken zu erfahren, wie es zur abschließenden Entscheidung kam. Er muss die Idee nicht noch einmal komplett durchdenken und erkennt sofort, wo er sich anders entschieden hätte oder Optimierungsbedarf sieht.

Konzept: Sind die ersten Gedanken einmal sortiert, formalisiert und niedergeschrieben, können Sie das Dokument zunächst als ersten Plan zur Umsetzung betrachten. Dieses Konzept kann nun schon einer größeren Runde von Entwicklern und am Projekt Beteiligten vorstellt werden. Es wird die wesentlichen Komponenten beschreiben und Risikoeinschätzungen sowie die Entscheidungsfindung beinhalten. Wenn dieses erste Konzept steht, ist der kreative Part (Abb. 1) des Designens, also die Anforderungen in ein Design zu übertragen, größtenteils abgeschlossen. Der Übergang von einem Konzept zu einer Spezifikation stellt dabei eine Gradwanderung dar. So können zum Beispiel Teile des Konzepts schon soweit ausgearbeitet sein, dass diese eine detailliertere Spezifikation nicht mehr benötigen. Aber andere Teile können immer noch im Stadium einer Ideensammlung feststecken und Markierungen wie „noch offen, todo, tbd.“ etc. enthalten.

Abb. 1: Die Möglichkeiten ein Design zu erläutern, reichen von kreativ skizzierend bis hin zu exakt dokumentierend

Spezifikation: Das technisch exakte Spezifizieren löst den kreativen Teil des Designprozesses nun endgültig ab. Ein SDD, das die Anforderungen an eine detaillierte technische Spezifikation erfüllt, sollte das gesamte Stück Software wie zum Beispiel eine Komponente eines größeren Systems beschreiben und kann es bis auf exakte Schnittstellen runterbrechen. Das heißt, technische Abhängigkeiten, wie zum Beispiel zu Datenbanken und weiteren externen Systemen, gehören in dieses Dokument als auch zu verwendende Frameworks, Patterns, Programmiersprachen bis hin zu Codeformatierungsrichtlinien und Vorgaben zur Codedokumentation. Schließlich muss in diesem Stadium die Konsistenz des Inhalts gegeben sein und die bereits erwähnten, als offen gekennzeichneten Stellen im Dokument dürfen nicht mehr auftauchen.

Dokumentation: Ist die Software fertiggestellt, getestet und abgenommen, können die bis dahin entstandenen SDD zunächst als Dokumentation für die Maintenance-Phase Verwendung finden. Allerdings hängt dies stark von der bis dahin erzeugten Ausprägung und der Aktualität der Dokumente ab. Ein paar lose Skizzen für die Wartungsphase der Applikation auf dem Schreibtisch liegen zu haben, zeugt dabei natürlich nicht von Professionalität.

Je nach Vorgehensmodell entstehen verschiedene Typen von Dokumenten. Beim Wasserfallmodell mit einer eigenen Designphase werden eher umfangreiche und ausgereifte Dokumente entstanden sein. Im iterativen oder agilen Prozess entstehen eher kleine Artefakte wie einzelne Diagramme mit kurzer Erläuterung und die Dokumentation im Code. Der Aufwand, eine Dokumentation für die Maintenance-Phase zu erstellen, ist daher bei einem agilen Vorgehen unter Umständen höher als bei wasserfallartigen Ansätzen.

Inhalt

Sprache und Ausdruck: Ein SDD beschreibt technische Zusammenhänge, Abhängigkeiten und Anforderungen. Die Ausdrucksweise ist daher eher nüchtern und ohne literarische Ausschweifungen. Der Text muss kurz und knapp auf den Punkt kommen und zwar auf verständliche Art und Weise. Sicherlich eine der größten Herausforderungen bei der Erstellung eines SDD. Die Intention des Aphorismus „So wenig wie möglich und so viel wie nötig“ ist dabei oft nicht einfach einzuhalten, da sie oft nur für eine Zielgruppe erfüllbar ist und nicht immer für jede Zielgruppe ein ganz neues Dokument erstellt wird. Fachliche abstrakte Anforderungen in etwas technisch Konkretes zu übersetzen und dies wieder so zu beschreiben, dass es je nach Zielgruppe auch ein technischer Laie nachvollziehen kann, wäre natürlich die Kür, ist aber eher selten zu leisten.

Versuchen Sie die Sprache im Dokument ausgewogen und konsistent zu halten. Sie können aber Kapitel in das Dokument einführen, die explizit für andere Stakeholder, wie zum Beispiel die Kollegen aus der Qualitätssicherung oder die Analysten, gedacht sind. Versuchen Sie dabei deren Sprache zu verwenden. Begeben Sie sich auf den Jahrmarkt und lernen Sie die Sprachen der Schausteller. Wenn Sie in dem entsprechenden Kapitel zum Beispiel die jeweiligen Fachtermini der Zielgruppe verwenden, werden deren Vertreter das Kapitel mit Interesse lesen und Feedback geben – den richtigen Gebrauch des Jargons vorausgesetzt (Kasten: „Zielgruppen-Jargon Beispiel“). Im Glossar des Dokumentes können dazu nicht geläufige Fachtermini kurz erläutert werden.

Zielgruppen-Jargon Beispiel
Sie entwickeln zwei Komponenten, die über verschiedene Schnittstellen kommunizieren. Um diesen Teil der Applikation zu testen, sind in der Regel sowohl Komponententests als auch Integrationstests von Interesse. Die Begriffe „Komponententest“ und „Integrationstest“ sind Fachtermini aus dem Bereich der Softwarequalitätssicherung und werden von Testern sofort verstanden, wenn Sie diese Art von Begriffen im Kapitel „Test der Komponente“ verwenden. Die Intention ist hier natürlich nicht dem Tester vorzuschreiben, welche Teststrategien er verwenden soll, aber dennoch sind sinnvolle Hinweise im jeweiligen Jargon eine gute Diskussionsgrundlage während eines Design-Reviews.

Struktur: Neben einer verständlichen und knappen Sprache ohne literarische Ausschweifungen und Wiederholungen gilt: Halten Sie die Struktur der entstehenden Dokumente konsistent. Wird Ihnen keine Struktur vorgegeben, können Sie sich an Standards oder Strukturen, die sich als Best Practice erwiesen haben, orientieren.

Als eine grobe strukturelle Trennung zugunsten der Übersichtlichkeit ist beispielsweise die Differenzierung von High-Level-Design und Low-Level-Design möglich. Ein High-Level-Design-Dokument stellt eher die architektonische Sicht [4] auf das ganze System mit seinen Komponenten dar. Neben der Komponentenübersicht enthält es unter anderem Kapitel zur Erläuterung von Laufzeitszenarien sowie Vorgaben für die Realisierung von nicht funktionalen Anforderungen. Dokumente, die die Softwarearchitektur beschreiben, unterliegen dabei nicht so häufigen Änderungen. Die Architektur enthält elementarste System- und Designentscheidungen, die oft nicht einfach zu ändern sind und daher eher selten geändert werden. Im Gegensatz dazu beschreibt ein Low-Level-Design eine spezifische Komponente zum Beispiel durch ein Klassenmodell mit Methoden und deren Signaturen detaillierter. Je nach Fortschritt des Designs können Sie sich aber auch in der Low-Level-Designdokumentation zunächst auf die zentralen Aspekte beschränken. Stellen Sie nur die wesentlichen Methoden einer Klasse dar – wenn überhaupt. UML-Tapeten sind auch hier fehl am Platze.

Die Idee hinter den propagierten Strukturen ist dabei immer das Wissen in versteh- und überschaubare Stücke zu zerlegen und dies anhand einer mehr oder weniger nachvollziehbaren Logik. Diese Logik basiert aber auch auf dem geplanten Design der Software; steht und fällt also auch mit den Designentscheidungen. Je mehr Sie eine Entscheidung beschreiben müssen, desto unlogischer kann die Entscheidung gewesen sein. Oder aber umso wichtiger!

Lässt sich das Design nicht in einfachen und klaren Sätzen und Diagrammen erläutern, oder müssen Sie zu weit ausholen, sollten Sie Ihren Ansatz vielleicht noch einmal überdenken. Schließlich soll die Dokumentation einen einfachen und schnellen Einstieg in das Design ermöglichen und von der darunterliegenden Komplexität der Software abstrahieren.

Der Schlüssel zum Code

Um diese Komplexität greifbar zu machen, müssen Sie sich zwangsläufig auf ein Abstraktionsniveau einlassen, das die zentralen technischen Ideen zur Realisierung der Software möglichst übersichtlich (Abb. 2) vermitteln kann und an Ihr Vorgehen angepasst ist.

Abb. 2: Ein Design übersichtlich und exakt zu beschreiben, kann durch die Fokussierung auf das Wesentliche gelingen

Je höher das Abstraktionsniveau ist, desto mehr Komplexität wird verdeckt, aber umso verständlicher kann die Beschreibung sein. Das bewusste Weglassen von Information, in unserem Falle technischer Details, ist eine der Ideen hinter dem Begriff Abstraktion [5]. Dies gelingt insbesondere durch das Herausarbeiten und Verallgemeinern von grundlegenden Faktoren einer Begebenheit, zum Beispiel eines technischen Problems bzw. einer technischen Lösung. Letztendlich sind einfache und abstrakt gehaltene SDD änderungsstabiler und in der Wartung kostengünstiger als SDD, die zu sehr ins Detail gehen und Aspekte erläutern, die besser im Code zu erfahren sind.

Betrachten Sie daher die Designdokumentation als Schlüssel zum Code der Software und denken Sie an den Leser, der ihn aufschließen will. Den Einwand, ein Entwickler hätte nur den funktionierenden Code abzuliefern, würde ich stets hinterfragen. In einem Autohaus werden die Fahrzeuge schließlich auch mit Schlüssel ausgeliefert und im Vorfeld darüber gesprochen.

Geschrieben von
Berthold Schulte
Berthold Schulte
  Berthold Schulte ist seit dreizehn Jahren als Softwareentwickler und Berater im Java-Umfeld tätig. Er arbeitet überwiegend in internationalen Projekten und befasst sich mit der Konzeption und Migration von global aufgestellten E-Commerce-Plattformen hin zu Cloud-basierten Ansätzen.
Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.