Stefan Zörner
14.01.2014
In diesem Beitrag geht es um einen unterbewerteten Abschnitt in arc42. Klare Begrifflichkeiten sind der Schlüssel, um Prinzipien innerhalb der Architektur zu etablieren. Und um sie überhaupt gut kommunizieren zu können.
OK: Glossar klingt jetzt nicht sooo spannend.
Das Inhaltsverzeichnis von arc42 enthält einige Abschnitte, wo auf den ersten Blick sonnenklar erscheint, was sie bergen. Das Glossar zählt wohl dazu.
Langweilig? Ich finde nein.
Für unser Vorhaben, Gradle nach arc42 gegliedert darzustellen, ist es wertvoll, und kommt eher zu spät.
Und als Ergänzung zur “klassischen” tabellarischen Form eines Glossars schlage ich eine grafische Ergänzung dazu vor. Nun doch gespannt?
Dann wieder: Schere raus und losgeschnippelt …
Immanuel Kant definierte in seinem berühmten Essay “Beantwortung der Frage: Was ist Aufklärung?” nicht nur eben diesen Begriff. Er klärte in dem Zusammenhang auch noch einige weitere. Hier der Beginn des Aufsatzes …
“Aufklärung ist der Ausgang des Menschen aus seiner selbstverschuldeten Unmündigkeit. Unmündigkeit ist das Unvermögen, sich seines Verstandes ohne Leitung eines anderen zu bedienen. Selbstverschuldet ist diese Unmündigkeit, wenn die Ursache derselben nicht am Mangel des Verstandes, sondern der Entschließung und des Mutes liegt, sich seiner ohne Leitung eines andern zu bedienen. Sapere aude! Habe Mut, dich deines eigenen Verstandes zu bedienen! ist also der Wahlspruch der Aufklärung. …” – Immanuel Kant, 1784
Kant stand mit vielen Zeitgenossen in schriftlicher Korrespondenz (z.B. mit Friedrich Schiller), und tauschte sich mit ihnen aus.
Auch bei der Kommunikation in Softwareentwicklungsprojekten ist es unerlässlich, dass die Beteiligten über dasselbe reden, wenn sie einen Begriff verwenden. Sonst reden sie buchstäblich aneinander vorbei.
Muster und Prinzipien sind typische Beispiele für Kategorien in der IT-Welt, in denen sich Begriffe und in Summe eine gemeinsame Sprache etabliert haben. Diese Begriffe sind in einflussreichen Fachbüchern geklärt. Die Philosophen der IT heißen nicht Nietzsche (“Gott ist tot.”, 1882) sondern Hunt (“Der pragmatische Programmierer”, 1999) oder Martin (“Clean Code”, 2008), … manchmal schreiben sie wie Kant einen Essay – heute in ihrem Blog. Sie fragen nicht “Was ist Aufklärung?” sondern zum Beispiel “Was ist Dependency Injection?” (Martin Fowler, “Inversion of Control Containers and the Dependency Injection pattern”, 2004) oder (ein weiterer Klassiker) “Was ist AOP?” (Adrian Colyer, “AOP without the buzzwords”, 2004).
Muster, Prinzipien und Paradigmen sind allgemeingültige Begriffe in der IT, wir lernen sie in Studium, Aus- oder Weiterbildung. Sie helfen uns im Projekt, die Konzepte und Ideen unserer Lösung an Dritte zu kommunizieren. Zum Beispiel an ein neues Teammitglied. Daneben gibt es noch Begriffe, die projektspezifisch sind. Und die ein neues Teammitglied, auch mit ähnlichem IT-Hintergrund, neu lernen muss, um mitreden zu können. Oft – aber nicht immer – sind sie fachlich motiviert. Hier hilft ein projektspezifisches Glossar.
Ein fachsprachliches oder technisches Glossar listet die Terminologie einer Fachsprache oder eines technischen Sachgebietes mit begrifflich-sachlichen Definitionen auf, die den richtigen Gebrauch dieser Fachausdrücke und deren eindeutiges Verständnis sichern sollen. – aus Wikipedia: Glossar
Die klassische Form eines Glossars ist tabellarisch. Die Begriffe in der ersten Spalte sind alphabetisch sortiert. Eine zweite Spalte beinhaltet die Erläuterungen. Falls in den Erläuterungen Glossarbegriffe verwendet werden, sind diese idealerweise geeignet gekennzeichnet.
Diese Form ist leichter zu benutzen und auch zu pflegen als ein Prosa-Text. Um beim Beispiel Kant zu bleiben sieht ein tabellarisches Glossar ungefähr so aus … (die jeweiligen Erläuterungen in der Tabelle sind Wikipedia-Artikeln entlehnt):
| Begriff | Erläuterung |
| Aufklärung | Epoche in der modernen westlichen Philosophie. Laut Kant der "Ausgang des Menschen aus seiner selbstverschuldeten Unmündigkeit" |
| Epoche | längerer geschichtlicher Abschnitt mit grundlegenden Gemeinsamkeiten |
| Kant | Immanuel Kant (1724-1804), deutscher Philosoph der Aufklärung |
| Mensch | höheres Säugetier aus der Ordnung der Primaten. Kann Fragen stellen, die in grundlegender Weise die eigene Existenz und Zukunft betreffen |
| ... | ... |
Ein neues Teammitglied wird sich sehr freuen, wenn es zum Start ein Projektglossar in die Hand gedrückt bekommt. Begriffe, die “der Neue” (oder “die Neue”) wiederholt aufschnappt, schaut er nach, und lernt sie schnell. Fehlt ein Begriff, oder wird ein Begriff inkonsistent benutzt, kann das neue Teammitglied das aufspüren, und aktiv zur Verbesserung des Glossars beitragen.
Bei umfangreichen Glossaren ist die Freude mitunter getrübt. Der ein oder andere wird sich an das Lernen von Vokabeln erinnert fühlen. Ich habe sehr gute Erfahrungen damit gemacht, ein tabellarisches Glossar mit einem Schaubild zu ergänzen. Ein solches grafisches Glossar zeigt in Form eines Graphen die wichtigsten Begriffe als Knoten. Verbindungen (Kanten) zwischen diesen Begriffen zeigen Beziehungen und können beschriftet werden. Die Kanten nehmen so weiteres Fachvokabular auf.
Als Beispiel, wie so etwas grafisch aussehen kann, habe ich mir nochmal den Text von Kant vorgenommen:
Wenn Sie einen Begriff nehmen, und die Kanten entlang wandern, können Sie Sätze lesen wie “Mensch bedient sich Verstand”. Ein grafisches Glossar zeigt also die Verwendung des Fachvokabulars in Verknüpfung. Doch nun genug philosophiert. Längst Zeit für unseren Serienstar Gradle!
Das folgende Diagramm zeigt einige wichtige Begriffe aus der Gradle-Welt und setzt sie in Beziehung zueinander. Die dargestellten Begriffe, und noch weitere, sind in der nachfolgenden Tabelle erläutert.
Die Zahlen an den Linienenden im Diagramm lassen sich z.B. lesen als “Ein Artifact wird veröffentlicht in keinem oder einem Repository”.
In den Erläuterungen der Tabelle sind verwendete Glossarbegriffe kursiv dargestellt.
| Begriff | Erläuterung |
| Artifact | physisches Ergebnis (Output) eines Builds. Zum Beispiel ein JAR-File, oder eine DLL. |
| Build | Ausführung des Build-Skriptes durch Gradle, Abarbeitung der Tasks. |
| Build-Script | Beschreibt ein Projekt (Project). Bei Gradle eine Textdatei als Input für den Build, formuliert in einer Groovy-basierten DSL. Wesentliche Bestandteile: Konfiguration, Abhängigkeiten zu externen Bibliotheken, Schritte (Tasks), und Abhängigkeiten zwischen den Schritten. |
| DSL | domänenspezifische Sprache (engl. domain-specific language), Wikipedia |
| Gradle | JVM-basiertes Buildsystem. Führt im Rahmen des Builds das Build-Script aus. |
| Groovy | dynamisch typisierte Programmiersprache und Skriptsprache für die JVM (Homepage) |
| JVM | Java Virtual Machine. |
| Plugin | Funktionalität von Gradle, die über Projektgrenzen hinweg wiederverwendet werden kann. Gradle liefert selbst zahlreiche Plugins mit ("Core Plugins"). Eigene Erweiterungen können ebenfalls als Plugins realisiert werden ("Custom Plugins"). |
| Project | Repräsentiert etwas, was im Rahmen des Builds in einem oder mehreren Schritten gebaut werden kann, und/oder passieren soll. Zum Beispiel das Bauen und Ausliefern von Software. |
| Property | Eigenschaft eines Projektes, einer Task, eines Repositories. Erlaubt deren Konfiguration und ist typischerweise mit sinnvollem Standardwert versehen ("convention over configuration", Wikipedia. |
| Repository | Quelle für externe Bibliotheken, von denen der Build abhängt. Oder Ziel für die Veröffentlichung (engl. publishing) von Artefakten (artifact). Beispiel: Maven Central. |
| Task | Einzelner Schritt innerhalb des Builds. Kann adhoc im Build-Script in Groovy definiert sein, oder Bestandteil eines Plugins, und im Skript verwendet. |
Das Gradle-Glossar hier im Blog-Beitrag ist ein erster Wurf. Am Ende der Startschnitt-Serie füge ich die Schnipsel zu einem geschlossenen Architekturüberblick zusammen. Bis dahin ergänze ich das Glossar. Daher freue ich mich über Anregungen zum Inhalt. Welche Begriffe fehlen aus Ihrer Sicht?
Im grafischen Glossar nehmen Sie nur zentrale Begriffe auf. Auch bei einem umfangreichen Glossar passt das Diagramm auf ein DIN-A4-Blatt. Das Bild ergänzt lediglich die Tabelle und dient dazu sich in die Begriffswelt einzufinden. Gerade bei umfangreichen Glossaren habe ich gute Erfahrungen mit diesen Bilder gesammelt; neue Mitarbeiter legen einen Ausdruck auf ihren Schreibtisch und schauen regelmäßig drauf.
Sie müssen auch nicht alle Kanten im Diagramm einzeichnen, die zwischen Ihren Begriffen möglich wären. Da alle aus einer Fachwelt stammen, gibt es immer eine mögliche Verknüpfung. Zeigen Sie aber nur die wichtigsten, vermeiden Sie ein Liniengewirr. Interessant sind vor allem solche Kanten, die Platz für weitere fachliche Begriffe bieten. Lassen Sie spannende Sätze entstehen, Ihr Glossar eine Geschichte erzählen!
Grafische Glossare, wie hier gezeigt, haben Ähnlichkeit mit Fachklassenmodellen der objekt-orientierten Analyse und Ansätzen im Domain-Driven Design. Für das Glossar ist entscheidend, dass die Diagramme intuitiv verständlich sind. Verzichten Sie auf eine Symbolflut (z.B. viele unterschiedliche Pfeilarten). Auch die Ergänzung um Attribute schießt am Ziel vorbei. Die Bilder sollen den Zugang zur Begriffswelt erleichtern. Wenn Sie die Notation erst erklären müssen, wird das schwieriger.
In arc42 ist für das Glossar der letzte Abschnitt 12 vorgesehen, siehe Abbildung.
Mitunter haben Sie in Ihrem Projekt bereits ein Glossar angelegt. Das Glossar in Ihrer Architekturbeschreibung sollte dazu passen, und die Begriffe konsistent dazu erklären. Am einfachsten verzichten Sie in solchen Fällen auf das Einfügen des Projektglossars in Ihr Architekturdokument und referenzieren es.
Ein Glossar, das speziell für einen nach arc42 gegliederten Architekturüberblick ausgedünnt wurde, ist auch eine Option. Der Überblick ist dann leichter zu lesen. Der Ansatz birgt durch die Redundanz gleichzeitig die Gefahr, dass die beiden Glossare auseinanderlaufen Hier sind technische Lösungen, die Glossarbegriffe zentral verwalten, interessant.
Den sechsten Gradle-Schnipsel zum farbig ausdrucken, ausschneiden und aneinanderkleben können Sie hier herunterladen. ;-)
In der nächsten Folge des Starschnitts verfeinern wir die Qualitätsziele aus Schnipsel #3 mit Hilfe von Qualitätsszenarien genauer. Solche Szenarien bilden eine Basis, um Entscheidungen zu begründen und zu bewerten.
Dieser Beitrag ist ursprünglich als Teil einer Blog-Serie beim Hanser-Verlag (“Hanser Update”) erschienen. Die Inhalte, ergänzt um reichhaltiges Bonus-Material, sind mittlerweile auch als E-Book bei Leanpub verfügbar.