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?

Teaser-Bild Folge #6

Dann wieder: Schere raus und losgeschnippelt …

Was ist Aufklärung?

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.

Von Kant zu Clean Code

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)

Glossare

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

Grafisches Glossar als Ergänzung

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:

Grafischer Glossar Kant

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!

– – – 8< – – –

Schnipsel #6 (Grafisches Glossar): Eine Glossar für 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.

Gradle_Glossar

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 Repä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.

– – – >8 – – –

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?

Wie fertigen Sie einen grafischen Glossar an?Schnipsel #6 herunterladen und farbig ausdrucken

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.

Wo kleben wir den Schnipsel hin?

In arc42 ist für das Glossar der letzte Abschnitt 12 vorgesehen, siehe Abbildung.

Glossar abheften in arc42

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.

Zum Weiterlesen

  • Glossare sind auch ein Dokumentationsmittel in meinem Buch Softwarearchitekturen dokumentieren und kommunizieren. Das Buch besitzt selber eine tabellarischen Glossar, der mit einem grafischen Glossar illustriert wird.
  • Eines der Fallbeispiele des Buches, eine Schach-Engine, ist online verfügbar und besitzt ebenfalls einen Glossar (keinen grafischen allerdings): Glossar DokChess
  • Der Wikipedia-Artikel zu Immanuel Kant enthält eine Illustration seiner Erkenntnistheorie, die in seiner Form einem grafischen Glossar wie hier gezeigt ähnelt.

Ausblick

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.

Ich hoffe, Sie finden weiterhin Gefallen an dieser kleinen Serie und freue mich auf Ihre Fragen und Rückmeldungen. Kommentieren Sie einfach hier im Blog oder schreiben Sie mir (E-Mail: stefan.zoerner[ät]embarc.de). Wünsche greife ich gerne in den nächsten Folgen auf, Fragen beantworte ich direkt hier.

Sie haben einen Schnipsel des arc42-Starschnitts zu Gradle verpasst? Hier finden Sie alle bisherigen Folgen.