Drei Dinge, die mich bei Architekturdiagrammen mit plantUML nerv(t)en

By 20. November 2016Allgemein, Inhaltliches

plantIch sehe bei Kunden ab und an plantUML im Einsatz. Und noch häufiger fragen mich Teilnehmer in Workshops, was ich von plantUML halte, wenn es um Diagramme in der Dokumentation von Softwarearchitektur geht. Beispielsweise in den betreffenden Abschnitten von arc42 (Konkret: Kontextabgrenzung, Bausteinsicht, Laufzeitsicht …).

Um ehrlich zu sein fand ich plantUML dafür lange Zeit nicht so toll. Aus verschiedenen Gründen. Bei näherem Hinsehen ließ sich einiges davon aber auf Unkenntnis und Vorurteile meinerseits zurückführen. Und einige Unschönheiten lassen sich mit den richtigen Kniffs und Workarounds umgehen. Ein paar kleine Erkenntnisse zeige ich im Rahmen dieses Beitrags. Und beginne so meinen Frieden zu machen mit dem Werkzeug.

Aber zuvor: Was ist dieses plantUML überhaupt (für diejenigen, die es nicht kennen) und warum finde ich es (immernoch) nicht ganz so toll wie manche meiner Kunden?

plantUML

plantUML generiert UML-Diagramme als Graphik aus textuellen Beschreibungen. Die Syntax dazu ist recht einfach gehalten und schnell erlernt. Hier ein Minibeispiel. Aus der Eingabe links generiert plantUML das Diagramm rechts.cd_schach

@startuml

Schachbrett -> Figur 
Figur --> Farbe
Figur --> enum Art

enum Farbe { 
 SCHWARZ 
 WEISS
}

@enduml

 

Neben den besonders gut unterstützen Klassendiagrammen (wie im Beispiel oben, Details zur Syntax siehe hier) kann plantUML auch andere Diagrammarten der UML generieren (Sequenzdiagramme, Anwendungsfalldiagramme …).

plantUML ist Open Source, in Java geschrieben und leicht integrierbar. Entsprechend gibt es zum Beispiel Plugins für verschiedene Textsysteme (z.B. Asciidoctor), Build-Werkzeuge (z.B. Gradle) und Wikis (z.B. XWiki und Confluence). Gerade in diesen Fällen passt das Text-Format von plantUML sehr gut, fühlt es sich doch in der Versionsverwaltung ebenso wohl wie zwischen Wiki-Markup.

In der Regel nimmt der Autor beim Erstellen kaum Einfluss auf das Layout seiner Diagramme. Ich sehe das als Vorteil, kostet das Kästchenschubsen in graphischen Editoren bei Änderungen doch oftmals viel Zeit.

Drei Dinge, die ich an plantUML nicht mag

Trotz der unbestrittenen positiven Merkmale gibt es Dinge, die mir bei plantUML nicht so gut gefallen. Hier drei aus meiner Sicht besonders gewichtige:

  1. Der Technologie-Stack ist fragil
  2. Für Softwarearchitektur relevante Diagramme fehlen
  3. Die generierten Diagramme sehen altbacken aus

Der Technologie-Stack ist fragil

plantUML ist in Java geschrieben, der Download lediglich ein jar-File. Tatsächlich handelt es sich bei bei dem Tool aber eher um ein Frontend (oder wenn man mag einen Präprozessor) für das Werkzeug Graphviz.

binaryGraphviz ist eine leistungsfähige und recht verbreitete Open Source-Lösung zum Visualisieren von Graphen (also Knoten verbunden durch Kanten). Anders als plantUML wird es Betriebssystem-spezifisch als Binary installiert. Es muss lokal vorliegen (konkret: das Graphviz-Executable „dot“). plantUML greift darauf zu, es verwandelt die plantUML-Eingabe in eine Eingabe in der DOT-Sprache und lässt dann Graphviz die ganze Arbeit machen („Zwerge auf den Schultern von Riesen“).

Das Problem dabei: das Zusammenspiel zwischen plantUML und dot führt regelmäßig zu Reibung. Auch eine saubere Graphviz-Installation verweigert schon mal die Arbeit und führt zu Fehlermeldungen, lustigerweise in Form einer Graphik anstelle des erhofften Ergebnisses. Sieht dann zum Beispiel so aus:

Fehler beim Aufruf von not / Graphviz

In der Praxis heißt das etwa für ein Java-Projekt, das seine Architekturdokumentation in den Build integrieren will, dass es höhere Anforderungen an das Build-System stellt. Also an alle, die das Projekt bauen wollen. Java installieren reicht nicht (wie bei Gradle durch den Wrapper eigentlich üblich), es muss auch noch Graphviz da sein und mit plantUML zusammenspielen.  Das berühmte „It Works on My Machine“ war doch eigentlich überwunden (OK, die Pest ist schlussendlich auch noch nicht ausgestorben). Auch entsprechende Beiträge der Plugin-Benutzer in den Foren von XWiki und Confluence singen ein Lied von dem Problem.

Für Softwarearchitektur relevante Diagramme fehlen

plantUML unterstützt verschiedene Diagrammarten der UML, und die wiederum verschiedenen gut. Bei Klassendiagrammen geht mit Abstand am meisten. Gerade diese Diegrammart benötige ich allerdings in einem Architekturüberblick eher selten, bestenfalls für ein grobes Domänenmodell.

struktur_kleinBesonders wichtig sind mir methodisch gesehen die Kontextabgrenzung (Kapitel 3 in arc42, bzw. der Abschnitt „Context“ bei Simon Brown) und die statische Zerlegung (Kapitel 5 „Bausteinsicht“ in arc42). Eine Kontextabgrenzung lässt sich mit plantUML ganz gut visualisieren übrigens. Meine favorisierte Darstellung von Zerlegungshierarchien mit den Ports der Kompositionsstrukturdiagramme unterstützt plantUML leider nicht. Strukturen lassen sich zwar mit gruppierenden Elementen abbilden; Interaktionspunkte auf der „Membran“ (Ports, siehe kleine Skizze links) gehen hingehen nicht.

Die Diagramme sehen altbacken aus

Geschmäcker sind verschiedenen, mir persönlich gefällt die Darstellung von plantUML tatsächlich nicht sonderlich. Die Buchstaben-Icons bei Klassen, Aufzählungen etc. (E, C, … siehe Schach-Beispiel oben)  sind nicht mein Fall, und vor allem:  Die Farben (gelbe Kästen, rote Linien) haben die Anmutung alter Rational-Werkzeuge (kleine Zeitreise, Video). Die Zeit wünsche ich mir nicht zurück. Den Retro-Look der 90er-Jahre komplett machen dann Komponenten im Stil der UML 1. Als Beispiel hier ein rudimentärer Systemkontext (System mit einem Benutzer als Akteur) in plantUML, rechts wieder das resultierende Diagramm (das System als Komponente in UML 1-Notation):

@startumlsc_altbacken
[Webshop] <<system>>
:Kunde: - Webshop
@enduml

Auf Diagramme mit dieser Anmutung stolpere ich regelmäßig in Projekten. Dass mir die nicht übermäßig gefallen ist mein Problem, wenn die Teams es so mögen … Mein Problem könnt Ihr gleichzeitig beheben, bei plantUML läßt sich nämlich so ziemlich jede Stileigenschaft (Fonts, Farben, Strichbreiten …) konfigurieren. Aber wer hat da schon Lust zu? Der Aufwand mit all den Schaltern schreckt erstmal ab.

Die gute Nachricht: Es gibt recht große Schalter — Hebel sozusagen — welche mit wenig Aufwand viel Wirkung zeigen. Für das Beispiel oben reichen zwei dieser wirkmächtigen Hebel, und es sieht für mich deutlich passabler aus (siehe wieder Graphik rechts):

@startumlsc_modern
skinparam monochrome true
skinparam componentStyle uml2

[Webshop] <<system>>
:Kunde: - Webshop
@enduml

Das gefällt mir richtig gut schon. Derartige Skin-Parameter lassen sich übrigens auch in Dateien auslagern, von aussen in den plantUML-Prozessor reinreichen, etc. — So verschmutzen sie auch nicht alle plantUML-Quelltexte.

Fazit

Der Ansatz, aus text-basierten Beschreibungen Graphiken/Diagramme zu generieren, hat viel für sich. In vielen Fällen nutzen Teams ein Wiki oder Text-Systeme wie Asciidoc, um ihre Architekturdokumentation festzuhalten. Die Frage, wo die Diagramme herkommen, stellt sich dort stets, und plantUML ist zumindest eine Option. Mit wenigen Kniffen finde ich die Ausgabe zumindest optisch passabel, eine große Herausforderung bleibt das fragile Zusammenspiel mit Graphviz.

Ich spiele mit dem Gedanken hier ein geschlossenes Fallbeispiel bereitzustellen. Einen Architekturüberblick, in dem die Diagramme mit plantUML generiert sind, und dessen Inhalte sich an den Sichten von arc42 orientieren. Fänden Sie das interessant?

8 Comments

  • Stephan Roth sagt:

    Hallo Stefan,
    super Beitrag, auch ich verwende gelegentlich plantUML für UML-Visualisierungen. Besonders hervorheben möchte ich auch die Möglichkeit einer Ausgabe der Diagramme im SVG-Format (Scaleable Vector Graphics), einem verlustfreien Vektorformat, welches sich sehr gut mit Inkscape (einem Open Source Vektorzeichenprogramm) nachbearbeiten lässt. Das finde ich immer dann praktisch, wenn ich UML-Darstellungen für Printerzeugnisse gestalten möchte, die ich ja dann aus Inkscape in sehr hoher Qualität exportieren kann.

    Allerdings gibt es grundsätzlich einen Haken: Das M in UML, welches ja für Modeling steht, wird nicht unterstützt, d.h. ich habe mit plantUML ja letztendlich auch nur etwas gezeichnet, wenngleich auch über den Umweg einer textbasierten Beschreibungssprache. Ein wirkliches Modell, wie es in echten Modellierungswerkzeugen entsteht, ist das nicht.

    Viele Grüße,
    Stephan

    • Hallo Stephan,
      vielen Dank für Deine schöne Rückmeldung!

      Da hast Du wohl recht, schlussendlich malt man nur Bilder, auch wenn man Text editiert. Grundsätzlich ist es möglich, Teile der plantUML-Beschreibung in separate Dateien auszugliedern, und von unterschiedlicher Stelle aus in verschiedenen Diagrammen einzubinden. Damit kommt man Deiner Modell-Idee schon etwas näher, der Ansatz überzeugt aber auch nur halb.

      Eher ein Schuh wird draus, wenn man plantUML-Beschreibungen per Transformation aus einem geeigneten Model ableitet. Und sei es aus einer Kreuztabelle in Excel (einer meiner Kunden macht das für Kontext-Abgrenzungen in seiner Systemlandschaft).

      Herzliche Grüße,
      StefanZ

  • Falk Sippach sagt:

    Schöner Artikel. Übrigens, PlantUML kann man mittlerweile auch ohne Graphviz rendern. Ist meines Wissens noch nicht stabil, aber schaut bereits ganz brauchbar aus.

    https://rdmueller.github.io/plantuml-without-graphviz/

  • Hallo Stefan,

    bezüglich Graphviz – es geht mittlerweile auch ohne! Ist zwar noch alpha, lässt sich aber schon prima einsetzen:
    https://rdmueller.github.io/plantuml-without-graphviz/

    …und PlantUML hat einen entscheidenden Vorteil bei Sequenz-Diagrammen: hier ist das automatische Layout klar von Vorteil!

    Gruss,
    Ralf

  • Jonas Riedel sagt:

    Einen Architekturüberblick als geschlossenes Beispiel wäre auf jeden Fall sehr interessant. Besonders die arc42 konforme Umsetzung mit plantUML !

  • Duc Luu sagt:

    Hallo Stephan,

    Schöner Artikel, ich arbeite auch gerne mit PlantUML, da Text basiert und in unser Firmenwiki integriert.

    Die Optik hat mich noch nicht so gestört. Das Schwarzweiß finde ich eher schlechter zu lesen. Probleme mit Graphviz hatten wir noch nicht.

    Ein Fallbeispiel für arc42 inkl. PlantUML-Sourcen fände ich sehr interessant und hilfreich.

    Viele Grüße
    Duc

  • Michael sagt:

    Schließe mich dem Wunsch eines Fallbeispiels ala arc42 an.
    Wir nutzen bereits das arc42 asciidoc template und haben mit der Nutzung plantuml begonnen.
    Auch wir haben damit nur gute Erfahrungen gemacht, bspw. die wirklich niedrige Hürde direkt im Pairing Diagramme zu „coden“ und somit auch Nachhaltig zur Verfügung zu stellen.
    Grüße
    MJ

  • Henning sagt:

    Schöner Artikel, der mir bzgl plantuml aus der Seele spricht. Habe irgendwie genau die gleichen Probleme wie ihr:
    * Abhängigkeit zu dot
    * Atlbackene Grafik .. ok, mit den Schaltern zu der grauen UML2 Notation könnte ich mich auch abgeben
    * Diagramme zeichnen ohne richtiges Modell dahinter und daraus resultierender Probleme

    Grade der letzte Punkt ist doch etwas, was auch mit Austausch mit anderen Modellen immer wieder Probleme macht. vor allem, wenn ich an die vielen „neuen“ Modelle und Architekturen denke, wie EAST-ADL, AUTOSAR ARXML. Generell aber auch mit dem Tooling, hier mal Rhapsody, dort ein AUTOSAR Editor (auf welcher Ebene auch immer), da Xtext, Xpand, Xtend oder Acceleo, JET, ATL, MTL, QVT … Ich meine, gerade im Automotive Embedded Bereich haben wir eigentlich anderes zu tun, als ständig irgendwas von A nach B zu transformieren, um damit schaffen zu können. Eigentlich wollen wir doch eine Architektur und Designs erstellen.

    Wegen zeichnen vs Modell, was würdet ihr eigentlich von textuml (http://abstratt.github.io/textuml) halten?

Leave a Reply