Im dritten Teil unserer Reihe mit Tipps für bessere Architekturdokumentationen haben wir uns um Pfeile gekümmert. Da liegt es natürlich nahe, einen Artikel hinterherzuschieben, der Tipps zum Malen von Kästchen in Architekturdiagrammen zum Thema hat. Und damit nicht der Eindruck entsteht, wir könnten nur Meckern, gebe ich heute lieber direkt ein paar Tipps, anstatt wie beim letzten Mal erst einmal Antipattern anzuprangern.

Im Internet gibt es bereits einige Artikel mit allgemeinen Tipps für bessere Architekturdiagramme, darunter beispielsweise das „1×1 guter Architekturdiagramme“ von Gernot Starke. Jacqui Read widmet sich vielen Aspekten dieses Themas mit ihrem Buch „Communication Patterns”. Mein Kollege Balthasar Weitzel hat in der Zeit als wir noch gemeinsam bei Fraunhofer tätig waren die Bachelor-Arbeit von Sophie Zakrzewski zu dem Thema betreut, die man sich auf Fraunhofer Publica anschauen kann.

In diesem Artikel möchte ich daher nicht die Tipps und Erkenntnisse aus anderen Artikeln nochmal neu besprechen, sondern auf einige Aspekte eingehen, die uns in unseren Projekten immer wieder auffallen. Wie beim letzten Artikel sind die folgenden Tipps so gestaltet, dass man sie direkt beim Modellieren ohne Mehraufwand umsetzen kann und Ihr damit zu höherer Präzision und besserer Verständlichkeit in Architekturdiagrammen kommt. Bestes Preis-Leistungs-Verhältnis, also.

Tipp 1: Gleiches gleich, Unterschiedliches unterschiedlich

Ihr kennt wahrscheinlich den Tipp, gleiche Arten von Elementen auch immer mit dem gleichen Symbol darzustellen, also beispielsweise alle Komponenten in allen Diagrammen gleich darzustellen und nicht einmal mit Kästchen mit Komponentensymbol und einmal ohne. Ich denke das ist intuitiv nachvollziehbar, Einheitlichkeit trägt nunmal zu Verständlichkeit bei.

Was mir in Projekten aber häufig begegnet ist der gegenteilige Fall, nämlich dass nicht sauber differenziert wird und sehr unterschiedliche Dinge mit den gleichen, meist sehr generischen Kästchen dargestellt werden. Beispielsweise werden gerne mal Daten gleichförmig neben Komponenten gestellt oder einzelne Komponenten kommunizieren mit eigenständigen Applikationen und sehen dabei ununterscheidbar aus.

Diese fehlende Präzision erschwert das Verständnis, weil man sich immer fragen muss, wovon jetzt eigentlich gerade die Rede ist und wo die betreffenden Elemente eigentlich im Code zu finden sind. Die folgende Abbildung zeigt ein Beispiel. Der Vergleich zwischen den beiden Diagrammen zeigt recht deutlich, wie unterschiedliche Arten von Elementen durch verschiedene Darstellungen besser unterscheidbar werden. Natürlich kann die Leser:in durch den Kontext und die Form bestimmte Informationen ableiten (beispielsweise dass es sich bei API, Business Logic und Persistence wahrscheinlich um Layer handelt), aber warum soll ich es der Leser:in schwerer machen als nötig? Dokumentation wird ja für die Leser:innen und nicht für die Ersteller:innen gemacht.

Pro Tip: In draw.io kann man sich eigene Shape Libraries anlegen, so dass man die wichtigsten Shapes immer griffbereit hat und nicht immer die Stereotypes von Hand eintragen muss. Am einfachsten geht das mit dem Scratchpad. Einmal eingerichtet entsteht damit bei der Verwendung von unterschiedlichen Elementen quasi kein Mehraufwand mehr.

Tipp 2: Kardinalitäten und Stellvertreter explizit machen

Aus der UML kennt Ihr wahrscheinlich die Kardinalitäten, die man an Beziehungen zwischen Klassen darstellt; 1:n-Beziehungen, m:n-Beziehungen etc. Gerade wenn man die Funktionsweise des Systems im Rahmen von Architekturkonzepten beschreibt, ist es äußerst hilfreich zu wissen, ob eine bestimmte Komponente (oder eine bestimmte Art einer Komponente) nur einmal oder mehrfach im System vorkommen kann. Die folgende Abbildung zeigt ein Beispiel.

Die Abbildung zeigt ein Konzept zur Erzeugung, Registrierung und Nutzung von bestimmten Service-Komponenten im System. Die genaue Bedeutung des Konzeptes ist hier nachrangig, was man aber gut sehen kann, ist die explizite Benennung, wie viele konkrete Komponenten es von jeder Art geben wird (bspw. eine pro Gesamtsystem, eine pro Domäne, viele pro Domäne), sowie die Verwendung von Stellvertretern (hier beispielsweise unter Verwendung von eckigen Klammern). Das ist insofern hilfreich, weil man damit deutlich macht, dass es sich bei diesen Komponenten um Platzhalter handelt, für die es im System konkrete Ausprägungen gibt. Der Text in eckigen Klammern kann als eine Art Variable verwendet werden; in der Abbildung könnte man [Domain] in der konkreten Ausprägung durch einen spezifischen Domänen-Namen ersetzen, so dass es beispielsweise in der Domäne „Order“ eine Komponente „OrderServiceInit“ und unterschiedliche DomainServices für verschiedene Features geben könnte.

Diese Art der Darstellung ist insbesondere für die Bescheidung von generischen Konzepten hilfreich, die dann wiederholt instanziiert werden, um so eine einheitliche Art der Umsetzung zu gewährleisten. Da wir in der Architektur ja nach Einheitlichkeit streben, kommen solche Darstellungen bei uns durchaus häufig vor.

Tipp 3: Keine Angst vor logischen Kästchen

Es kommt immer wieder vor, dass man ein Konzept hat, bei dem Systemteile zwar inhaltlich zusammengehören, aber an sehr unterschiedlichen Stellen im System zum Liegen kommen. Denkt beispielsweise an Erweiterungen für fachliche Domänen, die eigene UIs, Code-Teile und Daten mitbringen. Um das Verständnis in solchen Fällen zu erleichtern, empfiehlt es sich auch mit logischen Gruppierungen zu arbeiten, auch wenn diese keine oder nur eine indirekte Repräsentation im Code haben. Die folgende Abbildung zeigt ein Beispiel.

Hier sieht man ein System das basierend auf ausführbaren Geschäftsprozessen und Regeln basiert und erweiterbar ist um fachliche Domänen. Um eine Erweiterung durchzuführen sind spezifische Komponenten, Code-Fragmente und Regeln notwendig. Um die Zusammengehörigkeit explizit zu machen, werden im Diagramm Gruppierungen verwendet, die mit den Kästchen mit den gestrichelten Linien dargestellt sind. Diese haben keine direkte Manifestation als Artefakt im Code (sind also kein eigenes Package, Deployment Artifact, Container, oder ähnliches), dennoch helfen sie für das Verständnis, weil im Sinne der 7±2-Regel (Millersche Zahl) zusätzliche Chunks bilden, die man dann einfacher verarbeiten und merken kann. Man sollte deren Bedeutung aber natürlich im Text erläutern.

Tipp 4: Verwende Bekanntes

Menschen tun sich leichter neue Dinge zu verstehen, wenn sie sie auf etwas Bekanntes zurückführen können. Deswegen funktionieren Patterns auch so gut. Daher ist es auch bei der Erstellung von Architekturdiagrammen und beim Malen von Kästchen sinnvoll darauf zu achten, Darstellungen zu verwenden, die den Leser:innen bekannt sind. Dieser recht allgemeine Tipp hat zahlreiche unterschiedliche Ausprägungen. Hier einige Beispiele:

• UML: Es gibt zahlreiche Diskussionen ob es nun sinnvoll ist, die UML für die Modellierung von Architekturen zu verwenden oder nicht. Faktisch ist es aber so, dass viele Leute ein intuitives Verständnis für die wichtigsten Elemente der UML mitbringen, wie beispielsweise Komponenten, Interfaces, Klassen, oder Packages. Wir halten uns eigentlich nie sklavisch an alle Modellierungsvorgaben der UML, aber wir lehnen uns gerne daran an, weil die Darstellungen für viele Personen im Projekt leicht verständlich sind.
• Gebräuchliche Layouts und Formen: Es gibt einige ganz typische Darstellungen um bestimmte Sachverhalte auszudrücken. Dazu gehören beispielsweise: Persistenz / Datenbanken sind unten, UIs sind oben, Layers sind horizontal dargestellt, Cluster / fachliche Einordnungen vertikal, Sequenzen / Abläufe werden von links nach rechts und von oben nach unten dargestellt, wichtige Elemente kommen in die Mitte, etc. Wenn es keine absolut notwendigen Gründe gibt, diese Dinge anders darzustellen, sollte man sich unbedingt daran halten. Bilder, bei denen auf einmal die Datenbank doch oben ist, können zu völlig unnötiger Verwirrung bei den Leser:innen führen.
• Wiederkehrende Darstellungen: Wenn wir Architekturen dokumentieren, versuchen wir es so gut es nur geht, grundlegende Darstellungen des Systems bei der Beschreibung von unterschiedlichen Konzepten immer wiederzuverwenden. Sich wiederholende Darstellungen brennen sich in das Gedächtnis ein und unterstützen, dass sich ein gemeinsames Bild unter den Team-Mitgliedern formt.

Fazit: Bessere Kästchen, bessere Architekturdiagramme

Ich hoffe bei den Tipps war noch die eine oder andere Anregung für Euch dabei, über das hinaus, was man ohnehin schon aus Artikeln kennt. Wie auch im letzten Artikel, kann es mit den Kästchen #gleichrichtigmachen, wenn man ein paar einfache Tipps im Blick behält und kommt so ohne großen Mehraufwand zu besseren Architekturdiagrammen.