Software-Architektur Dokumentation

Freitag 10. Juli 2015

Die Software-Architektur Dokumentation dient vor allem diesen Zielen:

  • Eine schnelle und effektive Entwicklung ermöglichen
  • Das Entwicklungsprojekt —Zeiten, Ressourcenpräzise planen
  • Die regulatorischen Anforderungen an die Software-Architektur erfüllen
  • Die Weiterentwicklung des Systems und die Einarbeitung neuer Mitarbeiter erleichtern


Eine schnelle, effektive und planbare Software-Entwicklung wird v.a. dann gelingen, wenn man die Aufgabe (eine Software zu entwickeln, die den Software-Anforderungen genügt) in lösbare Teilaufgaben zerlegt und diese Teilaufgaben auf viele Entwickler verteilen kann.

Die Voraussetzung dafür ist eine präzise (Dokumentation der) Software Architektur, die leiderin vielen agilen Software-Entwicklungsprojekte zu kurz kommt.

Regulatorische Anforderungen an die Software-Architektur Dokumentation

Sowohl die IEC 62304 als auch die FDA fordern eine dokumentierte Software-Architektur, wobei die Forderungen der FDA über die der IEC 62304 hinausgehen. Letztere fordert eine Software-Architektur nur für Software-Systeme der Sicherheitsklassen B und C.

Software-Architektur: Forderungen der IEC 62304

Wenn Sie eine Software-Architektur dokumentieren und lediglich die Forderungen der IEC 62304 erfüllen wollen, müssen sie wenig beachten. Denn diese Norm verlangt im Wesentlichen nur fünf Dinge:

  1. Software-Komponenten identifizieren
  2. Schnittstellen zwischen Komponenten beschreiben
  3. SOUPs identifizieren, Anforderungen daran beschreiben
  4. Komponenten klassisifizieren (Default: Klasse C)
  5. Rückverfolgbarkeit (Traceability) sicherstellen

Software-Architektur IEC 62304 konform dokumentieren

Software-Architektur: Forderungen der FDA

Die FDA fordert bei der Software-Architektur darüber hinaus auch eine Beschreibung bzw. Modellierung des dynamischen Verhaltens wie man das üblicherweise mit Sequenz- oder Aktivitätsdiagrammen modelliert. Aber auch hier sollte das innere Verhalten der Software beschrieben werden, nicht das externe. Das ist ein Aspekt der Software-Anorderungen.

Beachten Sie, dass die FDA bei allen „levels of concern“ eine Software-Architektur verlangt. Nur müssen Sie die bei einem „minor level“ nicht einreichen.

Der Auditgarant zeigt Ihnen Schritt für Schritt, wie Sie eine Software-Dokumentation erstellen
Der Auditgarant zeigt Ihnen in, wie Sie eine FDA- und IEC 62304-konforme Software-Dokumentation (inkl. Architektur) erstellen.

Gedanken zu den Anforderungen an die Software-Architektur Dokumentation

Die regulatorischen Anforderungen an die Dokumentation einer Software-Architektur sind nur Minimalanforderungen und keine Best Practices: Eine Software zu beschreiben, ohne die dynamische Sicht zu beachten, erscheint als etwas zu „dünn“. Eine Software-Architektur ist dann gelungen, wenn

  • ein Programmierer daraus ohne große Rückfragen stellen (d.h. ohne ad-hoc Design-Entscheidungen treffen) zu müssen, daraus das Produkt entwickeln kann
  • und alle Anforderungen damit erfüllt werden können.

Beachten Sie: In einem professionellen Team findet die eigentliche Wertschöpfung beim (gemeinsamen) Denken und Diskutieren d.h. beim Entwerfen der Software-Architektur und nicht beim Kodieren statt!

Ein Auditor wird aber nur die Güte der Software-Architektur Dokumentation prüfen, nicht die Güte der Software-Architektur selbst.

Aufbau der Software-Architektur Dokumentation

Gliederung

Sie können das Software-Architektur Dokument gemäß folgender Kapitelstruktur gliedern:

  1. Metainformationen (z.B. Autor, System, Version, Datum, Ziel)
  2. Executive Summary
  3. Kontextabgrenzung
  4. Bausteinsicht
  5. Dynamische Sicht
  6. Verteilungssicht
  7. Querschnittsaspekte
  8. Entwurfsentscheidungen
  9. Risikomanagement und Sicherheitsklassifizierung
  10. Anhänge

Hinweis: Als Richtschnur, für eine „gute“ Dokumentation von Software-Architekturen empfehlen sich die ISO/IEC 42010 (guter Wikipedia-Artikel) und das Template von arc42.

Bausteinsicht

Mit das wichtigste Kapitel in der Software-Architektur Dokumentation ist die Bausteinsicht, die die statische oder logische Struktur im Sinne beschreibt. Aus regulatorischer Sicht sollten Sie zumindest die ersten beiden Hierarchieebenen des Komponentenbaums beschreiben, in nachfolgender Abbildung die blauen und grünen „Kästchen“.

Die Software-Architektur Dokumentation umfasst auch die Bausteinsicht (hier in drei Hierarchiebenen)

Die Software-Architektur Dokumentation muss die Bausteinsicht beinhalten. Hinweis: Diese Abbildung zeigt weder die Schnittstellen zwischen den Modulen noch nutzt sie eine Standardnotation wie UML

Sie haben zumindest zwei Möglichkeiten, dieses  Kapitel in der Software-Architektur Dokumentation zu strukturieren:

Variante 1

  1. Subsystem A
    1. Modul A1
    2. Modul A2
    3. Modul A2
  2. Subsystem B
    1. Modul B1
    2. Modul B2
    3. Modul B3
  3. Subsystem C
    1. Modul C1
    2. Modul C2
    3. Modul C3
    4. Modul C4

Variante 2

  1. Bausteinebene 1
    1. Subsystem A (Blackbox)
    2. Subsystem B (Blackbox)
    3. Subsystem C (Blackbox)
  2. Bausteinebene 2
    1. Subsystem A (Whitebox)
      1. Modul A1 (Blackbox)
      2. Modul A2 (Blackbox)
      3. Modul A2 (Blackbox)
    2. Subsystem B (Whitebox)
      1. Modul B1 (Blackbox)
      2. Modul B2 (Blackbox)
      3. Modul B3 (Blackbox)
    3. Subsystem 3 (Whitebox)
      1. Modul C1 (Blackbox)
      2. Modul C2 (Blackbox)
      3. Modul C3 (Blackbox)
      4. Modul C4 (Blackbox)

Umfang der Software-Architektur Dokumentation

Modellieren Sie „nur“ so genau, dass Sie keine adhoc Design-Entscheidungen mehr treffen müssen. Lieber ein kurzes und präzises Dokument als ein episches Werk, das keiner liest und auch nicht mehr aktuell ist.

40-50 Seiten ist eine gute Faustformel für den Umfang der Dokumentation Ihrer Software-Architektur. Das erreichen Sie dann, wenn Sie mit Bildern statt mit umfangreichen Texten arbeiten.

Wenn Sie Dinge genauer beschreiben wollen oder müssen, dann lagern Sie beispielsweise die Komponenten / Subsystem-Spezifikationen in eigenständige Dokumente  aus. Das empfehle ich besonders dann, wenn Sie diese Subsystem oder Komponenten in anderen Software-Systemen oder Produkten ebenfalls verwenden.

Prof. Dr. Christian Johner
Wünschen Sie Unterstützung dabei, Ihre Software-Architektur schnell, präzise und normenkonform zu dokumentieren, um eine wartbare Software in „Time & Budget“ entwickeln zu können? Professor Johner und sein Team helfen gerne! Nehmen Sie Kontakt auf!
War dieser Artikel hilfreich? Bitte bewerten Sie:
1 Stern2 Sterne3 Sterne4 Sterne5 Sterne

Kategorien: Software & IEC 62304
Tags:

Kommentar schreiben