Zugegeben, tolle Architekturdiagramme zu erstellen ist nicht einfach: gut strukturiert, klare Message, einfach zu verstehen, leicht zu merken, und so weiter. Es gibt zahlreiche Qualitätseigenschaften für Architekturdiagramme, die man unter einen Hut bringen muss. Trotzdem gibt es ein paar, sehr einfach umzusetzende Möglichkeiten um seine Architekturdiagramme substanziell zu verbessern. Im dritten Teil der Reihe mit Tipps für bessere Architekturdokumentationen (Teil 1 , Teil 2) möchte ich mit Euch über Pfeile sprechen.

In den folgenden Kapiteln möchte ich einige (nach meinem Empfinden) Antipatterns bei der Verwendung von Pfeilen in Architekturdiagrammen zeigen, die ich immer wieder in Projekten sehe und erläutern, was das Problem ist und wie man es besser machen kann. Das Schöne ist, dass sich alle Tipps in einfachster Weise und quasi ohne Mehraufwand umsetzen lassen. Natürlich kann es in konkreten Situationen immer gute Gründe geben, davon abzuweichen. Im Allgemeinen würde ich aber sagen, könnt Ihr in dieser Art ganz einfach zu besseren Architekturdiagrammen kommen.

Antipattern: Bidirektionale Pfeile

Ich halte bidirektionale Pfeile für ein problematisches Muster, weil sie in den meisten Fällen entweder ein Design-Problem oder aber einen Mangel an Präzision darstellen.

Handelt es sich bei dem Pfeil um die Darstellung des Kontrollflusses, würde eine bidirektionale Beziehung eine wechselseitige, also zyklische Abhängigkeit (siehe Wikipedia) darstellen. Diese kommt mit allerlei Problemen und sollten wir daher unbedingt vermeiden. In diesem Fall würde ich das Design meines Systems an dieser Stelle überdenken.

In den meisten Fällen wird mit bidirektionalen Beziehungen aber der Datenfluss dargestellt. Hier macht man sich es dann häufig einfach: „Da fließen Daten hin und her“. Aber dass wechselseitig, in gleicher Wichtigkeit und Menge, Daten in beide Richtungen fließen, ist eher eine Seltenheit. Klar, bei einem GET-Request schicke ich vielleicht einen Identifier mit und das ist dann ja auch ein Datum. Aber darauf kommt es in diesem Fall nicht an, sondern auf die Daten, die man als Ergebnis des Aufrufs zurückbekommt. Ich würde mir bei der Modellierung des Datenflusses also immer Gedanken machen, um welche Daten es in der Hauptsache geht und in welche Richtung sie fließen und dann dementsprechend den Pfeil einzeichnen.

Antipattern: Nackte Pfeile

Es gibt so viele Diagramme, bei denen einfach nichts an den Pfeilen dran steht. Damit reduziert sich die Aussage auf „ruft auf“ oder „da fließen Daten“. Aber was da eigentlich genau passiert, aus welchem Grund interagiert wird, welche Daten ausgetauscht werden, wie interagiert wird; alle diese wichtigen Informationen sind dann nicht enthalten. Die Ersteller:in sollte beim Einzeichnen des Pfeils aber ja durchaus klar sein, aus welchem Grund gerade eine Interaktion modelliert wird.

Daher ist meine unbedingte Empfehlung, das dann auch gleich dranzuschreiben. Dabei würde ich in den meisten Fällen eine inhaltliche Information (was passiert) der technischen (worüber wird kommuniziert) vorziehen. Also lieber „retrieve customer address“ als „http“. Wenn Ihr fancy seid, könnt Ihr ja auch beides kombinieren „retrieve customer address [http]“.

Antipattern: Was ist was?

Architekturdiagramme sind so unterschiedlich, dass nicht ohne Weiteres klar ist, was die verwendeten Pfeile ausdrücken, das heißt, von welchem Typ sie sind. Wenn sie beschriftet sind, kann man sich es manchmal herleiten, wenn nicht, wird es auch damit schwierig. Besonders verwirrend wird es, wenn mit Pfeilen in der gleichen Darstellung, unterschiedliche Arten von Interaktionen, also beispielsweise Kontrollfluss und Datenfluss gemischt dargestellt wird.

Deswegen, macht Euch klar, welche Art der Interaktion Ihr jeweils ausdrücken wollt. Wollt Ihr mehrere unterschiedliche ausdrücken, verwendet dafür auch Pfeile in einer unterschiedlichen Darstellung. Also beispielsweise welche mit durchgezogener Linie für den Kontrollfluss (Aufrufbeziehungen), Pfeile mit gestrichelter Linie für Datenfluss. Diese solltet Ihr dann natürlich auch so konsistent verwenden. Im besten Fall fügt Ihr einfach eine kleine Legende ein, anhand derer man die unterschiedlichen Arten direkt erkennen und unterscheiden kann.

Antipattern: Pfeile auf Container

Nicht immer ein Antipattern (aber häufig), sind Pfeile von oder zu Boxen, die als Container (nicht Docker) dienen, also die andere Komponenten gruppieren. Die transportierte Aussage ist in diesem Fall „Alle in dieser Box enthaltenen Komponenten dürfen alle in dieser anderen Box enthaltenen Komponenten aufrufen (und tun das potentiell auch)“. Dies ist aber meistens nur eine Abkürzung bei der Modellierung, die leider eine deutliche Einschränkung in der Aussagekraft nach sich zieht. Man sieht nämlich nicht mehr, welche Komponenten nun tatsächlich welche anderen aufrufen, aus welchem Grund, wie sie interagieren, etc.

Solche Container sind ja meistens eher logische, gruppierende Einheiten, die sich im Code vielleicht nur in einer Namenskonvention niederschlagen. Deswegen würde ich in den meisten Fällen versuchen, die Boxen als Startpunkt und Ziel einer Relation zu verwenden, die auch tatsächlich Logik ausführen. In dieser Weise lassen sich die Interaktionen, die auch tatsächlich stattfinden abbilden und so rücken Architektur und Code näher zusammen.

Fazit: Bessere Pfeile, bessere Architekturdiagramme

Macht Euch mal einen Spaß und sucht in der Google-Bildersuche mal nach „Software Architecture Diagram“, oder schaut mal Eure eigenen Diagramme an. Es ist bemerkenswert, wie viele Diagramme mindestens eins oder sogar alle der genannten Antipattern aufweisen. Dabei haben wir ganz einfach die Möglichkeit, bessere Architekturdiagramme zu erstellen; wenn wir uns um die Pfeile kümmern. Probiert es doch einfach aus!