Pragmatisch, aber vielseitig: Architekturdokumentation mit C4

Die Aussage "Abstraktion ist wichtiger als Notation" mag im ersten Moment wie ein Seitenhieb gegen klassische Modellierungsansätze wirken, ist aber nicht so gemeint. Eine einheitliche Notation ist nichts Schlechtes und kann definitiv bei der Kommunikation helfen. Die Erfahrung in der Realität zeigt jedoch, dass Ansätze, die eine strikte Notation vorgeben, oft nicht genutzt werden. Stattdessen verwenden Viele beim Erstellen von Diagrammen ihre ganz eigene Notation, meistens mit Entlehnungen aus gängigen Standards, aber eben doch nicht ganz nach Standard. Diese individuelle Notation erlaubt es, die Komplexität selbst zu bestimmen, ganz nach dem Motto "So detailliert wie nötig, so einfach wie möglich." Das Problem damit ist jedoch, dass unter den fehlenden Standards auch der Informationsgehalt leidet. Manche Diagramme platzen vor Details und sind unübersichtlich, andere Diagramme sind so minimalistisch, dass sie im Grunde allgemeingültig sind.

Bei C4 kann die Notation frei gewählt werden, dafür muss jedes Diagramm über eine Überschrift, eine Legende und jedes Element über eine Beschreibung verfügen. Auf diese Weise sind die Diagramme für jeden verständlich – auch für einen selbst, wenn man nach ein paar Monaten nochmal einen Blick darauf werfen möchte.

Darüber hinaus gibt es bei C4 gemeinsame Abstraktionen und ein eindeutiges Vokabular dafür. Die wichtigsten Begriffe sind "Software-System", "Container" und "Component". Ein Software-System bietet einem User, menschlich oder nicht, einen Mehrwert. Bei "Container" denken Viele direkt an Docker, der Begriff hat aber nichts mit den Docker-Containern zu tun! Beim Container handelt es sich gewissermaßen um die nächsttiefere Abstraktionsebene, ein Software-System setzt sich aus Containern zusammen. Ein Container kann beispielsweise eine Applikation oder ein Datenspeicher sein, vor allem aber kann er einzeln deployt werden. Ein Container besteht aus Components, die nächste Ebene. Eine Component ist eine Gruppierung von verwandten Funktionalitäten, die sich häufig hinter einem Interface befinden.

C4-Elemente im Überblick

• Person: Stellt eine menschliche Benutzerin des Software-Systems dar, z. B. (UML-)Akteure, Rollen oder Personen.
• Software-System: Höchste Abstraktionsebene; beschreibt etwas, das seinen Benutzerinnen einen Mehrwert bietet, unabhängig davon, ob diese Menschen sind oder nicht. In vielen Fällen ist ein Software-System "im Besitz" eines einzelnen Entwicklungsteams.
• Container: Nicht Docker! Ein Container repräsentiert eine Anwendung oder einen Datenspeicher. Ein Container muss ausgeführt werden, damit das gesamte Software-System funktioniert. Ein Container ist im Wesentlichen ein Kontext oder eine Grenze, innerhalb derer Code ausgeführt oder Daten gespeichert werden. Enthält Informationen über die verwendete Technologie wie Framework und Sprache.
• Components: Bausteine, aus denen ein Container besteht, beispielsweise eine Gruppe von verwandten Funktionalitäten, die hinter einer Schnittstelle gebündelt sind. Enthält Informationen zu dem benutzten Framework oder Entwurfsmuster und wie es angewendet wurde.
• Beziehung: Verbindung zwischen zwei Elementen. Immer unidirektional und mit Beschriftung. Beziehungen zwischen Containern (in der Regel stellen diese die Kommunikation zwischen Prozessen dar) sollten über eine explizit gekennzeichnete Technologie/ein Protokoll verfügen.

Diagramme müssen die Realität widerspiegeln

Dass Diagramme die Realität wiedergeben sollen, ist einleuchtend; Dokumentation, die nicht mit der Realität übereinstimmt, ist nicht hilfreich. Ein gewisser Verlust ist jedoch unabdingbar, da die Dokumentation eine Zusammenfassung der Informationen sein soll. George Fairbanks verwendete in seinem Buch "Just Enough Software Architecture" den Begriff "Model-Code Gap", um die Diskrepanz zwischen Codebasis und den daraus erzeugten Diagrammen zu bezeichnen.

Was genau bedeutet das?
Man stelle sich eine Codebasis vor, die dann in Form von Diagrammen dokumentiert wird. Nun gibt man einer Person, die die originale Codebasis nicht kennt, die Diagramme und bittet sie, nur auf Basis der Diagramme eine neue Codebasis zu erzeugen. Die Abweichungen der beiden Codebasen voneinander sind gewissermaßen das "Model-Code Gap". Waren die Diagramme aussagekräftig, die Informationen gut verständlich und eindeutig und die Darstellungen vollständig, werden die Codebasen nicht allzu sehr voneinander abweichen. Sind die Diagramme jedoch abstrakt, unstrukturiert und schwer verständlich, kann die Abweichung beliebig groß werden.

Ein essenzieller Bestandteil des C4-Ansatzes, der dabei hilft, das Model-Code Gap möglichst gering zu halten, ist die Einbeziehung von Technologie-Entscheidungen in die Diagramme. Zu wissen, welche Sprache, welches Framework, welche Protokolle verwendet wurden, würde die Unterschiede bei unseren zwei fiktiven Codebasen schon massiv verringern. Deswegen ist es bei C4 nicht nur möglich, sondern geboten, diese technischen Informationen in die Diagramme einzufügen, allerdings mit einem Augenmerk auf die Zielgruppen.

Verschiedene Zielgruppen brauchen verschiedene Informationen

Womit wir beim letzten Punkt angelangt wären: Verschiedene Zielgruppen benötigen verschiedene Informationen. Wie bereits erwähnt, sind technische Details prinzipiell wichtig, jedoch nicht für jede Zielgruppe relevant. Genauso verhält es sich auch mit Feinheiten der Architektur und Implementierungsdetails.

Die Lösung von C4 für dieses Problem ist gleichzeitig auch namensgebend: Es gibt vier Abstraktionsebenen, von einem groben Überblick bis hin zu Details auf Code-Ebene, die auch zunehmend mehr technische Details enthalten. Die oberste Ebene und damit das erste Diagramm ist das "System-Context-Diagramm", das ein Software-System in seinem Kontext darstellt, das heißt, es zeigt alle Personen und Software-Systeme, die mit diesem Software-System interagieren. Als Nächstes gibt es das "Container-Diagramm", welches alle Container eines Software-Systems zeigt und wie diese miteinander, aber auch mit anderen Software-Systemen und Personen interagieren. An dritter Stelle ist das "Component-Diagramm", dass alle Components eines Containers darstellt und wie sie untereinander, mit anderen Containern desselben Software-Systems und anderen Software-Systemen und Personen interagieren. Zu guter Letzt gibt es noch das Code-Diagramm, das den Code innerhalb einer Component dokumentiert. In den meisten Fällen ist es nicht sinnvoll, diese Diagramme für Dokumentationszwecke zu erstellen, da sie den größten Pflegeaufwand haben und bei Bedarf von der Entwicklungsumgebung generiert werden können.

Neben diesen "Standard-Diagrammen" gibt es noch einige Diagramme, die später hinzugefügt wurden und die Architekturdokumentation sinnvoll erweitern beziehungsweise ergänzen. Es gibt das "System-Landscape-Diagramm" und wie der Name schon vermuten lässt, handelt es sich hierbei um eine Übersicht der gesamten Systemlandschaft. Außerdem gibt es das "Dynamic-Diagramm", eine vereinfachte Version des UML-Kommunikationsdiagramms, und das "Deployment-Diagramm", eine vereinfachte Version des UML-Deployment-Diagramms.

C4-Diagramme im Überblick

System-Context-Diagramm 

• Inhalt: Personen, Software-Systeme
• Ziel: Zeigt das Software-System im Kontext seiner Umgebung. Es stellt die Interaktionen des Systems mit Benutzern und anderen Software-Systemen dar.
• Zielgruppe: Primär Management, Projektleitung, Produktmanagement, Kundinnen und andere Beteiligte ohne technischen Hintergrund, die ein allgemeines Verständnis des Software-Systems benötigen. Sekundär Systemadministration, Entwicklerinnen, Software-Architektinnen und andere Beteiligte mit technischem Hintergrund, die einen groben Überblick brauchen.
• Best Practices: Auf den Kontext des ausgewählten Systems beschränken. Die Besonderheiten oder Abhängigkeiten anderer beteiligter Systeme gehören hier nicht hin, sondern in die Dokumentation dieser Systeme. Außerdem gilt: Details sind hier nicht wichtig; Technologien, Protokolle usw. sind Informationen für niedrigere Ebenen.

Container-Diagramm 

• Inhalt: Personen, Software-Systeme, Container
• Ziel: Beschreibt die Architektur auf Container-Ebene, wie Anwendungen, Datenbanken oder Dienste innerhalb des Systems interagieren.
• Zielgruppe: Primär Systemadministration, Entwicklerinnen, Software-Architektinnen und andere Beteiligte mit technischem Hintergrund, die das technische Setup verstehen müssen. Sekundär Projektleitung, Produktmanagement und andere nicht-technische Beteiligte, die einen tieferen Einblick in die technischen Details wünschen.
• Best Practices: Ab diesem Level sind technische Details besonders wichtig, daher gilt, dass hier Informationen wie verwendete Technologien, Protokolle, Frameworks etc. aufgeführt werden. Informationen über die Infrastruktur selbst gehören hier allerdings nicht hin, diese sind in einem Deployment-Diagramm besser aufgehoben.

Component-Diagramm

• Inhalt: Personen, Software-Systeme, Container, Components
• Ziel: Zeigt, wie ein einzelner Container intern in Components zerlegt ist und wie diese zusammenarbeiten.
• Zielgruppe: Entwicklerinnen, Software-Architektinnen und andere technische Beteiligte, die an der Implementierung arbeiten.
• Best Practices: Nur erstellen, wenn es sinnvoll und die Detailtiefe gegeben ist. Technische Informationen sind hier ebenfalls wichtig, werden also genau wie im Container-Diagramm hinzugefügt.

Code-Diagramm 

• Inhalt: UML oder andere Darstellungsformen für Code
• Ziel: Geht auf die Implementierungsdetails einzelner Components ein, zum Beispiel in Form eines Klassendiagramms.
• Zielgruppe: Personen, die direkt am Code arbeiten.
• Best Practices: Eine Erstellung dieser Diagramme ist oft nicht notwendig, da sie bei Bedarf von der IDE erzeugt werden können. Sollten nur erstellt werden, wenn es wirklich notwendig, die Software sehr langlebig und die Erstellung automatisiert ist.

Weitere Diagramme

System-Landscape-Diagramm 

• Inhalt: Personen, Software-Systeme
• Ziel: Zeigt die gesamte Systemlandschaft. Es stellt die Interaktionen mit Benutzern, externen Systemen und anderen Schnittstellen dar und gibt einen grundlegenden Überblick über die Systemlandschaft.
• Zielgruppe: Technische und nicht-technische Beteiligte, die ein allgemeines Verständnis der Systemlandschaft benötigen.
• Best Practices: Gerade für größere Systemlandschaften sehr sinnvoll. Sollte nicht zu sehr ins Detail gehen, sondern einen allgemeinen Überblick ermöglichen, enthält daher nur Personen und Software-Systeme als Elemente.

Dynamic-Diagramm

• Inhalt: Software-Systeme, Container, Components
• Ziel: Hilfreich, wenn man abbilden will, wie die Elemente zur Laufzeit miteinander interagieren.
• Zielgruppe: Abhängig vom gezeigten Scope; sowohl technische als auch nicht-technische Beteiligte.
• Best Practices: Nur bei Bedarf erstellen, um einen komplexen Ablauf darzustellen oder wiederkehrende Muster zu dokumentieren.

Deployment-Diagramm

• Inhalt: Deployment Environments, Deployment Nodes, Software System Instances, Container Instances, Infrastructure Nodes
• Ziel: Stellt dar, wo eine Instanz eines Software-Systems/Containers ausgeführt wird, z. B. physische, virtualisierte oder Container-Infrastruktur.
• Zielgruppe: Primär Systemadministration, Software-Architektinnen und Personen, die für die Infrastruktur verantwortlich
  sind. Sekundär Entwicklerinnen und andere technische Beteiligte, die einen Überblick über die Runtime-Umgebung brauchen.
• Best Practices: Dieses Diagramm enthält alle wichtigen Informationen zur Infrastruktur. Eine konkrete Benennung der genutzten Technik, Geräte und Technologie ist ebenso wichtig wie das Dokumentieren der Adressen von Endpunkten.

Der "Diagrams-as-Code-2.0"-Ansatz erweitert das ursprüngliche Konzept, indem Darstellung und Inhalt getrennt werden. Statt der einzelnen Diagramme beschreibt man direkt die Architektur selbst in einer DSL und definiert dann, welche Diagramme erzeugt werden sollen. Die grafische Darstellung der Diagramme passiert getrennt von der Definition des Inhaltes und kann beliebig angepasst werden, es wird kein Standard vorgegeben. Das ist von Vorteil, da es in einem Projekt häufig Beteiligte gibt (oft mit nicht-technischem Hintergrund), die mit gängigen Standards wie UML nicht in der Tiefe vertraut sind. Vordefinierte Standards sind außerdem oftmals sehr komplex und blähen dadurch die Dokumentation unnötig auf. Durch die separate Definition der grafischen Darstellung ist es möglich, sich etwas zu definieren, das für den eigenen Anwendungsfall gut geeignet ist. Dieser Ansatz gestattet es, Änderungen an der Architektur ohne großen Aufwand in die Dokumentation zu übernehmen, da immer nur eine Codebasis gepflegt werden muss, in der die Architektur beschrieben wird.

Mithilfe von Tools wie Structurizr oder Structurizr Site Generatr können die Diagramme direkt als vollständige html-Seite erzeugt werden, die die miteinander verlinkten Diagramme enthält, sodass die Beziehungen zwischen den einzelnen Diagrammen schnell klar werden. Diese Tools erzeugen außerdem automatisch eine Legende für jedes Diagramm und binden vorhandene Überschriften ein. Alles das macht die Dokumentation gerade für Personen ohne Vorwissen über die Software deutlich zugänglicher.