Category

Inhaltliches

Beitragsbild_Bauteil_1

Ein erster Service mit Java und Spring Boot (Micro Moves, Bauteil 1)

By | Inhaltliches | No Comments

Blog-Serie Micro Moves -- LogoNachdem ich in der Intro den fachlichen Rahmen für die Schach-Anwendung FLEXess aufgespannt habe, gibt es in diesem Beitrag den ersten inhaltlichen Service: games. Oder genauer gesagt eine erste Fassung davon — denn der Service wird noch ein paar Verbesserungen erleben über die Zeit (u.a. ein UI). Die Quelltexte für den Service findet Ihr auf GitHub. Die Bezeichner in Quelltext und API (Klassennamen, Methodennamen etc.) sind Englisch. Das erschwert das Verständnis mitunter. Denn die Englischen Schachbegriffe erschließen sich selbst Schachkennern nicht automatisch. Das gilt bereits für grundlegende Dinge wie Figurennamen. Ich habe daher eine kleine Randnotiz dazu geschrieben:  Lady hits farmer … (?) Schachbegriffe auf Englisch. Doch bevor wir in den Quelltext eintauchen … zunächst: Was kann der Service fachlich?

Unser erstes Bauteil: Der games-Service

Bauteil 1Mit diesem Service können Anwender vorhandene Schach-Partien abfragen, inklusive deren Details (z.B. die gespielten Züge). Sie können neue Partien einleiten und sich dabei die Farbe aussuchen. Sie können offenen Partien als zweiter Spieler beitreten. Und sie können Züge ausführen.

Partien besitzen dabei drei Zustände:

  • OPEN: Die Partie ist offen, ein Spieler steht fest, ein weiterer kann beitreten
  • RUNNING: Die Partie läuft und die zwei Spieler machen abwechselt ihre Züge
  • ENDED: Die Partie ist beendet.

Die hier gezeigte Fassung des Services ist der Startpunkt. Einige Dinge fehlen noch und kommen in weiteren Folgen der Serie hinzu. Hierzu zählen insbesondere

  • Fachlich: Die Überprüfung der Schachregeln bei Zügen — das übernimmt später ein eigener Service. In dieser Fassung werden nur wenige Dinge geprüft, um zu sehen, wie der Service auf fehlerhafte Züge reagiert
  • Technisch: Ein User Interface — der Service bietet zunächst lediglich eine REST-Schnittstelle
  • Technisch: Das Thema Security — diesem Aspekt widmen wir einen eigenen Beitrag

Zunächst geht es darum einen ersten integralen Bestandteil von FLEXess mit überschaubarem Aufwand ans Laufen zu bekommen. Die rote (1) markiert Euren Standpunkt („Sie befinden sich hier.“).

Überblick FLEXess inkl. Position des Services games

Als eine charakteristische Eigenschaft von Microservices (und auch Self-containes Systems) wird oft die Freiheit in Technologieentscheidungen angeführt, welche die umsetzenden Teams genießen. Hier ist vor allem die Persistenz ein Thema, aber auch die verwendete Programmiersprache. Unterschiedliche Programmiersprachen innerhalb einer Anwendung sind kein Wert an sich, aber Flexibilität an dieser Stelle eröffnet bei verschiedenen Anforderungen ggf. interessante Optionen.

Der erste Service hier ist in Java umgesetzt. Um einen technologischen Mix zu zeigen folgen später noch Services in Python und JavaScript.

Die Umsetzung — Spring Boot als Microservices Chassis

Microservices Patterns (MEAP)Im Java-Umfeld ist der Einsatz von Spring Boot zur Implementierung leichtgewichtiger Services sehr verbreitet. Folgt man der Nomenklatur von Chris Richardson und seinem Buch Microservices Patterns (Cover siehe links) handelt es sich hierbei (gemeinsam mit Spring Cloud) um die Umsetzung des „Microservice Chassis“-Musters.

Als solches kümmert es sich um querschnittliche Aspekte. Laut Pattern-Beschreibung besteht der große Vorteil eines Microservice-Chassis darin, dass Ihr schnell und einfach mit der Entwicklung eines Microservices beginnen könnt. Oder wir jetzt hier konkret mit Spring Boot und Java.

Spring für sich alleine genommen ist ein verbreitetes, umfangreiches Java-Framework mit langer Geschichte. Spring Boot behauptet von sich selbst eine vorgefertigte Meinung über das Bauen von produktionsreifen Spring-Anwendungen zu haben. Es favorisiert Konventionen über Konfigurationen und ist so gemacht, dass Ihr so schnell wie möglich in Betrieb gehen können.

Die Umsetzung — Implementierung in Java

Microservices und Self-contained Systems sind Architekturstile mit Vertikalen als prägende Elemente. Eine einzelne Vertikale selbst kann geschichtet sein, so auch unser games-Service (wenn auch nicht strikt, wenn wie das folgende Abhängigkeitsdiagramm zeigt).

Abhängigkeiten zwischen den Paketen (Graphik: TeamScale)Die Java-Klassen sind auf drei Pakete verteilt:

Package org.flexess.games… Wesentliche Inhalte
domain Die Entitäten Game und Move und der Zugriff auf die Persistenz mit Spring Data.
service Geschäftslogik in der Klasse GameService. Greift auf die Repositories aus domain zu.
rest REST-Schnittstelle für den Service in der Klasse GameRestController.

Game übernimmt die Rolle eines Aggregates im Sinne von DDD. Objekte der Klasse Move verhalten sich dabei wie Bestellpositionen im kanonischen Aggregate-Beispiel einer Bestellung.

Als Persistenz kommt eine relationale Datenbank zum Einsatz (aktuell die H2), auf die der Service vermöge Spring Data JPA zugreift. Das Schema wird dabei aus den Entitäten generiert — wir wollten ja „schnell“.

Die Klasse GameService beinhaltet die oben beschriebene Funktionalität (Partien abfragen, Züge ausführen etc.) als Methoden. Auf dieser Ebene liegen auch die Transaktionen.

Die REST-Schnittstelle nutzt Spring Web MVC und Data Transfer Objects, um die Entitäten für die JSON-Repräsentation anzupassen ohne an den Domain-Objekten herumzufummeln. Eine sehr hilfreiche Informationsquelle für Anpassungen dieser Art ist Jackson Annotation Examples von Eugen Paraschiv.

Den Service bauen und starten

Den Quelltexten liegt ein Build-Skript für Gradle bei. Beim Bauen mit dem Gradle-Wrapper muss lediglich Java 8 (oder höher) installiert sein. Das Skript gradlew (bzw. gradlew.bat) lädt die passende Gradle-Version und startet den Build, der die Abhängigkeiten (wie zum Beispiel Spring) herunterlädt.

Das Target bootRun baut den Service, lässt Tests laufen und startet das Ganze lokal auf Port 8080. Hier eine Sequenz zum Klonen aus GitHub, bauen und starten …

$ git clone https://github.com/embarced/micro-moves.git
Cloning into 'micro-moves'...
$ cd micro-moves/modules/games/
$ ./gradlew bootRun

 

Service games startet mit Spring Boot

Den Service nutzen (Abfragen)

Beim ersten Hochfahren legt der Service eine H2-Datenbank an und ein paar Partien darin ab, damit Ihr ohne größere Umstände direkt abfragen könnt.

Ein guter Einstiegspunkt ist das Auflisten aller Partien mit http://localhost:8080/api/games/, das Ihr im Web-Browser eingeben oder auch in einem Terminal per curl abfragen könnt. Details zu einer einzelnen Partie erhaltet Ihr mit dem Hineinnavigieren mit der gameId in der URL. Hier ein Beispiel mit curl:

$ curl http://localhost:8080/api/games/
[{"gameId":1,"playerWhite":"pinky","playerBlack":"brain","status":"ENDED"},
{"gameId":2,"playerBlack":"peter","status":"OPEN"}]
$ curl http://localhost:8080/api/games/1
{"gameId":1,"playerWhite":"pinky","playerBlack":"brain","status":"ENDED",
"result":"0-1","activeColour":"w",
"fen":"rnb1kbnr/pppp1ppp/8/4p3/6Pq/5P2/PPPPP2P/RNBQKBNR w KQkq - 0 3",
"created":"2018-04-24T11:10:55","modified":"2018-04-24T11:10:55"}
$  

Die Ausgabe im Terminal ist nicht gut lesbar. Web-Browser können das schöner formatieren (hier im Screenshot Safari).

Wer Kommandozeilenfreund und Ästhet zugleich ist wie ich verwendet einen Pretty Printer wie json_pp:

$ curl http://localhost:8080/api/games/1 | json_pp
{
   "gameId" : 1, 
   "playerWhite" : "pinky", 
   "playerBlack" : "brain",
   "status" : "ENDED",
   "result" : "0-1",
   "activeColour" : "w",
   "fen" : "rnb1kbnr/pppp1ppp/8/4p3/6Pq/5P2/PPPPP2P/RNBQKBNR w KQkq - 0 3", 
   "created" : "2018-04-24T11:10:55",
   "modified" : "2018-04-24T11:10:55"
}
$

Eine Partie speichert neben den beteiligten Gegnern auch den aktuellen Zustand auf dem Brett in FEN-Notation ab (zu FEN siehe die Randnotiz Spielsituation als Zeichenkette hier im Blog). Die Abfrage aller Partien bzw. gezielt einer einzelnen Partie erfolgen über GET-Requests, die in den Methoden allGames bzw. gameById der Klasse GameRestController implementiert sind. Es lassen sich auch die Züge einer Partie anzeigen, etwa mit http://localhost:8080/api/games/1/moves/

Eine neue Partie anlegen (via curl und Postman)

Eine neue Partie einleiten erfolgt über einen POST-Request (Methode createGame) der auch über curl abgesetzt werden kann. Die verwendeten Kommandozeilenoptionen: -H kurz für –header, -X kurz für –request, -d kurz für –data).

$ curl -H "Content-Type: application/json" -X POST 
-d '{"playerWhite": "stefan"}' http://localhost:8080/api/games/
Game #3 (stefan-???) created.
$curl http://localhost:8080/api/games/3 | json_pp
{
   "playerWhite" : "stefan",
   "fen" : "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
   "gameId" : 3,
   "status" : "OPEN",
   "activeColour" : "w",
   "created" : "2018-04-24T12:51:47",  
   "modified" : "2018-04-24T12:51:47"
}
$

Das ist etwas mühsam und wäre es noch mehr, wenn weitere Angaben in den Daten erforderlich wären. Weitaus bequemer ist der Einsatz des schönen Werkzeuges Postman. Hier lassen sich u.a. auch Anfragen speichern und recyceln. Der Screenshot unten zeigt einen erfolgreichen POST zum Erzeugen einer neuen Partie. Tabea spielt schwarz.

Screenshot Postman

Ich habe hier ein Postman-Projekt mit den vom games-Service aktuell unterstützten Operationen abgelegt. Ihr könnt es leicht in Eure Postman-Installation importieren. Nicht gezeigt habe ich hier beispielsweise das Ausführen von Zügen, das über POST-Requests auf der …/moves/-Resource  abgebildet ist.

Weitere Informationen — und wie es weiter geht …

API-Design: Praxishandbuch für Java- und Webservice-EntwicklerDer Entwurf einer REST-API folgt Best Practices und Konventionen, die oftmals Projekt-spezifisch sind. Es gibt viele Dertailentscheidungen zu treffen. Etwa zum Aufbau der URLs oder zu Fehlercodes. Zum API-Design hat Kai Spichale ein lesenswertes Buch verfasst (Cover rechts), das auch REST-Schnittstellen behandelt.

Eine Schachpartie mit Postman oder curl zu spielen ist recht mühsam. Der Service braucht offensichtlich noch ein User Interface. Bevor ich mich diesem Thema annehme gibt es aber in der nächsten Folge zunächst noch einen weiteren Service. Diesen dann in Python.

Ach ja: Fragen und Anregungen sind natürlich jederzeit gerne Willkommen. Per Kommentar hier im Blog oder gerne auch per Mail direkt an mich.

Zur Blog-Serie Micro Moves

 

ContextMap_FLEXess_

Micro Moves – Zeitgenössische Softwarearchitektur als Bausatz (Intro)

By | Inhaltliches | No Comments

Logo Micro Moves Vertikale Architekturstile wie Microservices und Self-contained Systems sind in aller Munde. Beispiele für deren Umsetzung mit einer konkreten Technologie, etwa Spring Boot, finden sich reichlich im Netz. Bestimmte Aspekte kommen in der Diskussion meiner Meinung nach allerdings zu kurz — vor allem konzeptionelle. Hierzu zählen etwa die UI-Integration zwischen unterschiedlichen Services und Security-Themen — und ganz generell die Frage nach Makro- und Mikroarchitektur. Was ist für alle Services gleich? Wo profitiert Ihr von speziellen Lösungen? Wie fühlen sich unterschiedliche Technologien an, auch vielleicht im Vergleich zu Sachen die Ihr kennt?

In den nächsten Wochen entsteht hier daher FLEXess (für FLEXible chESS Platform), eine technologisch bunte Online-Schach-Plattform. Zug um Zug zum direkt Nachvollziehen (und Nachbauen). Mit Vertikalen realisiert in unterschiedlichen Programmiersprachen (Java, Python, JavaScript, …). Und querschnittlichen Aspekten wie UIs (von Web-Front mit SPA bis zur nativen App). Sowie der Gelegenheit als menschlicher Spieler gegen den aktuellen Ranglistenersten im Computer-Schach anzutreten.

FLEXess — Zug um Zug eine technologisch bunte Online-Schach-Plattform

Am Beispiel entlang diskutiere ich in dieser Serie wichtige Fragestellungen rund um Technologien und Vorgehen. Ich beantworte sie konkret für unsere Applikation und implementiere sie exemplarisch (Quelltexte auf GitHub). Weiter zeigt die Serie Alternativen auf und skizziert mögliche nächste Schritte. Darüber hinaus verweist jede Folge auf weiterführende Literatur und aus unserer Sicht qualitativ hochwertige Quellen im Netz.

Ihr wollt unterschiedlichste Technologien in einer überschaubaren aber gleichzeitig attraktiven Applikation gemeinsam am Werkeln sehen? Ihr wollt Eurer Wissen zu modernen Architekturstilen und Microservices Patterns auf- oder ausbauen? Und Orientierung in typischen Architekturentscheidungen erhalten.

Na dann los!

Der fachliche Rahmen

FLEXess erlaubt es den Benutzern gegeneinander Schach zu spielen, oder sich mit Computer-Gegnern zu messen. Fachlich zerfällt das ganze in Themen, die wir in unterschiedlichen Teilsystemen implementieren. Für die fachliche Zerlegung größerer Systeme etabliert sich in der Praxis der strategische Teil von Domain-driven Design (DDD). Zentraler Zerlegungsbegriff sind (Sub-)domänen. DDD kategorisiert diese in Core Domains, Supporting Domains und Generic Subdomains  und etabliert Muster der Zusammenarbeit für Teams, welche diese Teile umsetzen.

Ich möchte dem Thema hier gar nicht viel Raum geben — eine grobe Context Map zur Visualisierung der Fachlichkeit soll genügen:

Context Map FLEXess

Subdomäne Begriffe (Auswahl) Aufgabe / Verantwortlichkeit
Laufende Partien Gegner, Partie, Zug Einleiten und verwalten laufender Partien
Spieler Spieler Verwaltung der (menschlichen) Spieler, Registrierung etc.
Spielregeln Position, Züge Überprüfen von Zügen auf Gültigkeit, Test auf Partie-Ende …
Diagramme Bild Generierung von Schachdiagrammen als Graphiken (z.B. als PNG) zur Einbindung in Webseiten, Berichte etc.
Computer-Gegner Chess Engine Anbindung von Computerschachprogrammen

Nick Tune: The Strategic Practices of Domain-Driven DesignStatt der Standardliteratur zu DDD möchte ich Interessierten die schöne Materialsammlung von Nick Tune zum Thema Strategisches DDD ans Herz legen! In dem klasse gestalteten E-Book beschreibt der Autor Techniken wie Business Canvas, Event Storming etc.

In unserer Blogserie soll der Schwerpunkt jedoch auf der Umsetzung liegen.

Unsere Umsetzung: Ein Überblicksbild

Eine allgemein akzeptierte Definition für Microservices gibt es nicht. Und schlußendlich ist es auch egal, ob unsere Umsetzung einen Architekturstil „gültig“ implementiert. Gerade bei Microservices gibt es viel Gestaltungs- und Entscheidungsspielraum.

Martin Fowler und James Lewis beschreiben in Ihrem viel beachteten Blogbeitrag, der gerne als Definitionsersatz für Microservices mißbraucht wird, von einem Ansatz, der eine einzelne Anwendung mit Hilfe kleiner Services umsetzt. Diese laufen in eigenen Prozessen und kommunizieren über leichtgewichtige Mechanismen.

Die folgende Abbildung gibt einen groben Überblick über die Umsetzung von FLEXess, wie sie in den folgenden Wochen hier entstehen soll. Änderungen nicht ausgeschlossen, sondern umgekehrt wahrscheinlich.

Überblick FLEXess

Die folgende Tabelle ordnet die vertikalen Services den fachlichen Subdomänen aus der Context Map oben zu und nennt die wesentlichen verbauten Technologien und den Blogbeitrag, in dem sie erstmalig eingeführt werden …

Service Subdomäne Wesentliche Technologien Blog-Beitrag
chess-diagrams Diagramme Python, Flask, Pillow Folge 2
games Laufende Partien Java, Spring Boot Folge 1
rules Spielregeln
players Spieler

FLEXess unterstützt Web-Browser als UIs, weiterhin bietet es eine native Android-App für einen Teil seiner Funktionalität an (das Spielen von Partien). Als Kommunikation kommen im Wesentlichen HTTP und REST zum Einsatz, asynchrone Kommunikation über Messaging. Ein Reverse Proxy lässt die darunter liegenden Vertikalen (Services), die als eigenständige Prozesse laufen, wie eine Anwendung erscheinen.

Aber der Reihe nach.

Wie geht es weiter?

Wir beginnen in den nächsten Folgen mit der Umsetzung der ersten zwei Services. Anschließend diskutieren wir die UI-Frage — klassische Web-Applikation vs. SPA (Single Page Applikation) etc. — und stellen die zwei Vertikalen in einem Browser zur Verfügung. Den Anfang macht aber das Partien-Subsystem „games“ mit einer rein REST-basierten Schnittstelle …

Ach ja: Fragen und Anregungen sind natürlich jederzeit gerne Willkommen. Per Kommentar direkt hier oder gerne auch per Mail direkt an mich.

Zur Blog-Serie Micro Moves

viennaJS meetup_OZeigermann

Vienna JS Meetup: React and Typescript

By | Inhaltliches, Publikationen | No Comments
„ViennaJS & React Joint Meetup: React and Typescript.“

ViennaJS & React Joint Meetup

Vienna JS Meetup: React and Typescript
Speaker: Oliver Zeigermann and Dave Bruderstein
presented at React Vienna + Vienna JS joint event
July 26, 2017 at 7pm
Sektor5, Siebenbrunnengasse 44, 1050 Vienna

Video recorded by pusher

Oliver and Dave gives a practical demo about using React and Typescript – a brief introduction of what Typescript feels like.
No slides, just code.

React and Typescript. No slides, just code. - pusher session

follow us on Twitter – @embarced

bild_architectur_kata_SToth

Architektur Kata Live – Eine Rückschau

By | Allgemein, Inhaltliches, Publikationen, Vorträge | No Comments

Auf dem Software Architecture Summit 2017 in München habe ich einen halbtägigen Architektur Kata Workshop durchgeführt. Hier ein kurzer Einblick inklusive der erarbeiteten Ergebnisse und Präsentationsfolien. Mehr Informationen zu Architektur Kata gibt es auch in meinem Buch Vorgehensmuster für Softwarearchitektur

„Architektur Kata Live“
Logo Software Architecture Summit
 
Architektur Kata Live
Sprecher: Stefan Toth
Halbtagsworkshop auf dem Software Architecture Summit, München
Dienstag, 14. März 2017, 10 – 13 Uhr
Novotel München Messe, Willy-Brandt-Platz 1, 81829 München Riem

Was ist Ihrer Meinung nach wichtig, um als Sportler Erfolg zu haben? Genetische Veranlagung? Talent? Geld? Glück? Je nach Sportart werden diese Dinge mehr oder weniger Einfluss haben, fest steht jedoch: Alle Sportler trainieren und steigern ihre Leistungsfähigkeit zwischen den Wettkämpfen. Auch Tänzer, Moderatoren oder Musiker bereiten sich professionell auf ihre Aufgaben vor – sie tanzen, machen Sprechübungen, lernen oder proben. In Architektur Kata wird diese Professionalität auf Softwarearchitektur übertragen. Das Konzept der „Kata“ ist dabei Kampfsportarten entliehen, die damit die wiederholte Ausführung von Bewegungsabläufen im Übungsumfeld bezeichnen, um im Ernstfall gerüstet zu sein.
Was wir auch in Projekten und Firmen schon gemacht haben, wurde nun auf die große Teilnehmergruppe am Architecture Summit adaptiert. Über fast 70 Teilnehmer zwängten sich in einen etwas zu kleinen Raum und erhielten die Möglichkeit Systeme zu entwerfen, technisch relevante Fertigkeiten einzusetzen und ihre Ideen kreativ festzuhalten. Wiederholt, abwechslungsreich und im Vergleich mit anderen.

Die ausgewählten Architektur Kata waren „Real Fantasy NFL“ und „Lights, please“. Beide direkt von der ehemaligen Webseite des Erfinders Ted Neward (Teds Kata Seite) und sehr unterschiedlich. Einmal geht es um eine hochskalierbare und äußerst elastisch umzusetzende Webseite für Fantasy Football inkl. Highlight Videos, einmal um Heimautomatisation und die damit zusammenhängenden Herausforderungen für einen Elektronikartikelhersteller.
In Gruppen arbeiteten die Teilnehmer insgesamt etwa 1:15 an ihrer Lösung und an ihrem Problemverständnis. Lösungen wurden gegenseitig vorgestellt und bewertet. Hier die Gruppenergebnisse:

Hier gibt’s noch die Folien der Session zum Download.

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

By | Allgemein, Inhaltliches | 8 Comments

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?

Die sieben Regeln für gute Dokumentation in Stein gemeißelt? — Tafel 3 (von 3)

By | Allgemein, Inhaltliches | No Comments

In den zwei vorherigen Beiträgen hatte ich bereits mit der kurzen Diskussion der klassischen sieben Regeln für gute Dokumentation begonnen. Ich schließe sie in diesem Beitrag mit den beiden verbleibenden Regeln 3 und 7 ab. Hier noch einmal kurz zur Erinnerung alle sieben im Überblick:

Sieben Regeln für gute Dokumentation
book
1. Schreibe aus Sicht des Lesers. (Tafel 1)
2. Vermeide unnötige Wiederholungen. (Tafel 2)
3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation. (Tafel 3)
4. Verwende eine Standardstrukturierung. (Tafel 2)
5. Halte Begründungen für Entscheidungen fest. (Tafel 1)
6. Halte Dokumentation aktuell, aber auch nicht zu aktuell. (Tafel 2)
7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit. (Tafel 3)

Vermeide Mehrdeutigkeit. Erkläre Deine Notation (Regel 3)

Es ist unstrittig, dass sich bestimmte Informationen mit Bildern besser kommunizieren lassen als mit Text allein. Das gilt für Strukturen (Elemente und deren Beziehungen untereinander) ebenso wie für Abläufe (Folgen von Aktionen mit Alternativen, Wiederholungen, Parallelität). Ab einer gewissen Komplexität lässt sich das mit Stichpunkten oder Prosa nicht gut beschreiben. Diagramme und mitunter auch Screenshots kommen ins Spiel, bei Diagrammen ist in der Softwarearchitektur immer noch UML recht verbreitet.

In diesem Zusammenhang höre ich in Projekten oft: „Wir benutzen für unsere Architekturdiagramme UML. Die Notation ist standardisiert. Kann jeder lesen.“ Das mit dem standardisiert stimmt, meine Erfahrungen mit „kann jeder lesen“ sind andere.

In der Projektpraxis werden übrigens oft gar keine Architekturdiagramme angefertigt. Auch weil die Teammitglieder unsicher in der Notation sind. Sie glauben sie müssten UML nehmen aber haben Angst sich damit zu blamieren. Aus meiner Sicht ist UML zu verwenden kein Automatismus, und bei den vielen Zielgruppen (vgl. Regel 1) wird auch bei der UML Erklärungsbedarf da sein.

In diesem Zusammenhang zwei persönliche Ratschläge von mir rund um Diagramme:

  • Schreibt zu jedem Diagramm einen Satz der auf den Punkt bringt was zu sehen ist (“Mission Statement”, Kernaussage). In der Dokumentation (egal ob Dokument, Wiki, Poster …) platziert Ihr diesen Satz oberhalb der Abbildung.
  • Lasst Euch nicht von der Notation behindern. Benutzt stattdessen wenige Elemente, und erklärt diese in einer Legende.

Der erste Tipp sorgt zum einen dazu, dass Betrachter nicht rätseln müssen, was Ihr mit dem Bild sagen wollt. Zum anderen (und das ist das Entscheidende) hilft es Euch zu entscheiden, ob etwas „noch ins Bild reingehört“ oder nicht. Ihr vermeidet Diagramme voller Prachtfülle, in denen der Leser die relevanten Informationen dann aber suchen muss wie in einem Wimmelbild. Hier ein schönes Fundstück aus dem Netz dazu (Quelle, beachtet die beschönigende Überschrift).

complex-system-architecture-diagram-2292510

Immerhin: Eine Legende hat dieses Diagramm. Die Regel „Erkläre Deine Notation“ wende ich durchaus auch auf UML an. Und wenn Ihr dort wenige Elemente verwendet braucht Ihr auch nur wenig erklären. Die wenigen UML-Elemente dann aber bitte richtig verwenden. Sonst verwirrt Ihr diejenigen, die UML lesen können (gibt es auch).

Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit (Regel 7)

Hinter dieser Regel stecken Reviews, zumindest suggeriert das Wort „überprüfen“ das. Dokumentation kann man auf zwei Arten überprüfen. Die erste nenne ich gern „Überprüfung auf Standardkonformität“. Hier werden Kriterien an die Dokumentation gelegt und Fragen folgender Art gestellt (Beispiele):

  • Hat die Architekturbeschreibung mindestens 60 Seiten?
  • Ist sie nach arc42 gegliedert?
  • Ist jeder Abschnitt ausgefüllt?
  • Wird für die Diagramme als Notation UML verwendet?
  • Hat jedes Diagramm eine Legende?

Fragen dieser Art eignen sich prima für Checklisten, diese können in der Regel von einer QS-Abteilung abgearbeitet werden. Mitunter erfordern regulative Randbedingungen einen solchen Check auf Standardkonformität. Mit der Überprüfung auf Gebrauchstauglichkeit ist aber etwas anderes gemeint.

Nämlich dass die Dokumentation tatsächlich bei der Arbeit unterstützt. Diejenigen, welche Architektur kommunizieren wollen, und diejenigen, welche sich dafür interessieren. Also für Architekturtreiber, Lösungsansätze, Entscheidungen, Konzepte. Die geschlossenen Fragen von oben können das nicht leisten.
Architektur-Spicker #1, Seite 3
Die Überprüfung auf Gebrauchstauglichkeit findet als Test mit den Zielgruppen statt. Und hier schließt sich der Kreis von Regel 7 zu Regel 1 („Schreibe aus Sicht des Lesers“). Das Anfertigen eines Architekturüberblicks stelle ich überhaupt gerne als Kreislauf dar (initial klein Starten, dann schrittweise Verfeinern). Eine Darstellung dieser Idee findet Ihr zum Beispiel in unseren Architektur-Spicker #1 („Der Architekturüberblick“, Download als PDF) auf Seite 3 oben.

Die sieben Regeln für gute Dokumentation in Stein gemeißelt? — Tafel 2 (von 3)

By | Allgemein, Inhaltliches | No Comments

In einem früheren Beitrag hatte ich bereits mit der kurzen Diskussion von zwei der sieben Regeln für gute Dokumentation begonnen. Hier geht es weiter. Nochmal kurz zur Erinnerung alle Regeln im Überblick:

 

book

1. Schreibe aus Sicht des Lesers. (Tafel 1)
2. Vermeide unnötige Wiederholungen. (Tafel 2)
3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation.
4. Verwende eine Standardstrukturierung. (Tafel 2)
5. Halte Begründungen für Entscheidungen fest. (Tafel 1)
6. Halte Dokumentation aktuell, aber auch nicht zu aktuell. (Tafel 2)
7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit.

Starten möchte ich mit einer Regel die falsch angewendet sogar richtig Schaden anrichten kann. Der vierten.

Verwende eine Standardstrukturierung (Regel 4)

Wenn Ihr Dokumentationszutaten über den Quelltext hinaus anfertigt (beispielsweise Schritt-für-Schritt-Anleitungen zu übergreifenden Themen wie Persistenz oder Security) stellt sich die Frage wo Ihr das Ganze ablegt und strukturiert. Dies vierte Regel wird gerne als Reklamesatz für arc42 herangezogen. arc42 stellt eine Standardgliederung für Architekturbeschreibungen dar (in D-A-CH De-facto-Standard).
list-2
Tatsächlich findet alles irgendwie seinen Platz in arc42 (der Abschnitt „Konzepte“ entpuppt sich dabei in der Praxis als Joker). Ich rate Euch aber davon ab, Architekturdokumentation initial anzufertigen, in dem Ihr eine vollständige arc42-Gliederung (immerhin 12 Abschnitte) geschlossen z.B. als Word-Dokument „ausfüllt“.

Den Wert von arc42 sehe ich vor allem im Nennen möglicher Zutaten einer Dokumentation, die zusätzlich zum Quelltext im Team entstehen. Die Kontextabgrenzung etwa, oder Qualitätsziele. Hier gibt es übrigens große Überdeckungen zu Alternativen. Die arc42-Gliederung selbst hat dann ihren großen Auftritt, wenn Ihr eine Architekturbeschreibung aus den einzelnen Bestandteilen für eine bestimmte Zielgruppe zusammen setzt. Darüber hinaus hilft die Struktur auch beim Verwalten der Teile.

Standardgliederungen funktionieren übrigens auch in kleinerem Rahmen gut. Muss nicht gleich die ganze Architekturbeschreibung sein. Beispielsweise bei Schnittstellen und Entscheidungen ist die immer gleiche Struktur hilfreich. Sie gibt den Erstellern Sicherheit und Orientierung. Im Falle von Architekturentscheidungen unterstützt sie auch das Treffen derselben (die Dokumentation fällt ab). Dieser Beitrag enthält eine praxisbewährte Gliederung für Architekturentscheidungen.

Der Schaden, den diese vierte Regel nun anrichten kann, entfaltet sich in Kombination mit der nächsten.

Vermeide unnötige Wiederholungen (Regel 2)copy

Beim Nachdenken über diese Regel stolpere ich über das Wort „unnötig“. „Don’t repeat yourself“ ist ein prominentes Prinzip (auch DRY). Wenn hier explizit von „unnötigen“ Wiederholungen die Rede ist, scheint es auch solche zu geben, die nötig oder zumindest OK sind. DRY gibt mehr Orientierung … Was will und Regel 4 sagen?

Falls Ihr Architekturdokumentation wie oft gesehen in einem arc42-Dokument in Word anfertigt, geratet Ihr bei Anwendung von „Schreibe aus Sicht des Lesers“ (Regel 1) in ein Problem: Ein einziges Dokument  wird mehrere Zielgruppen nicht gerecht. Widersteht dem Reflex, einzelne Dokumente für die jeweiligen Zielgruppen anzufertigen (gute Idee eigentlich), und die betreffenden Inhalte dann jeweils hinein zu kopieren (schlechte Idee). Ihr lauft Gefahr, dass sich die geklonten Inhalte unabhängig voneinander ändern, und/oder habt hohe Wartungsaufwende.

Fertigt die Inhalte stattdessen jeweils einmal kleinteilig an, und führt sie bei Bedarf in unterschiedlichen  Dokumenten oder anderen Formen zusammen. Am besten geht dies automatisiert, etwa im Rahmen des Build-Prozesses. In der Projektpraxis sehen wir als Formate hier eher Markdown oder (häufiger) AsciiDoc als Word. Diese fühlen sich in einer Versionsverwaltung wohl; diff und merge funktionieren prima. Mit Hilfe von Includes entstehen passende Dokumente für unterschiedliche Zielgruppen durch Rekombinieren der Inhalte. Dieser Beitrag stellt eine entsprechende Werkzeugkette mit Markdown und Maven bzw. alternativ Gradle vor.

Ebenso wie einzelne Architekturdokumentation für unterschiedliche Zielgruppen durch Cut/Copy/Paste zu erzeugen solltet Ihr keine umfangreichen Inhalte aus anderen Teilen der Dokumentation (Klassiker: Anforderungen) in Eure Dokumentation kopieren. Verweist auf sie. OK ist aus meiner Sicht eine knappe Zusammenfassung, um den Lesern das Verfolgen des Links zu ersparen, die nur einen Überblick haben wollen. Hier handelt es sich um einen Kompromiss zwischen leichter Lesbarkeit und Wartbarkeit. Das führt zu Wiederholungen, die im Sinne der Regel OK sind.

Halte Dokumentation aktuell, aber auch nicht zu aktuell (Regel 6)file-2

Veraltete Dokumentation ist häufig eine Ausrede um überhaupt nicht zu dokumentieren. Dahinter stecken zwei Annahmen:

  1. Dokumentation veraltet sowieso
  2. Veraltete Dokumentation ist wertlos

Dazu lässt sich sagen: Eine festgehaltene (Architektur-)Entscheidung veraltet keineswegs, solange Ihr nicht von ihr abweicht. Vielleicht würdet Ihr heute anders entscheiden, mittlerweile haben sich Rahmenbedingungen oder Ziele geändert, Optionen sind dazugekommen, Annahmen haben sich als falsch herausgestellt. Kurz: Ihr seid schlauer. Um die Entscheidung nachvollziehen zu können ist aber der Zeitpunkt der Entscheidung relevant. Und da Architekturentscheidungen typischerweise schwer zurückzunehmen sind, ist eine spätere Umentscheidung unwahrscheinlich. Wenn Eurer Team in bestimmten Ausnahmefällen von dieser Entscheidung abweicht, ist es erst recht lohnenswert, diese Tatsache festzuhalten und das Wissen darum zum Beispiel an Neue weiterzugeben. Merke: Dokumentation unterstützt Kommunikation.

Neben den dokumentierten Entscheidungen gehören vor allem Lösungskonzepte und Mittel, die es leichter machen im Quelltext zurecht zu finden, in Eure Architekturdokumentation. Zu letzteren gehören Diagramme, die Strukturen und Abläufe zeigen (ungeliebte und unangefochtene Notation: UML). Die Wahrscheinlichkeit, dass Konzepte und Diagramme veralten, nimmt mit dem Detaillierungsgrad zu.

Veraltete Dokumentation weicht von der Lösungsrealität (dem Quelltext) ab. Das Team hat Änderungen und Ergänzungen also nicht nachgezogen.

Ich lese diese Regel daher vor allem so: Wenn Ihr merkt, dass Ihr viel Aufwand zum Nachziehen betreiben müsst, fragt Euch, ob dieser in einem gesunden Verhältnis zum Nutzen steht. Falls nein: Abstrahieren oder Automatisieren:

  • Abstrahieren — die Dokumentation beschreibt keine Lösungsdetails, sondern liefert einen Überblick
  • Automatisieren — Teile der Dokumentation werden z.B. im Rahmen des Builds aus dem Quelltext abgeleitet

Und die anderen Regeln?

In einem weiteren Beitrag hier im Blog führe ich die Diskussion mit den verbliebenen zwei Regeln fort. Bleibt dran …

Die sieben Regeln für gute Dokumentation in Stein gemeißelt? — Tafel 1 (von 3)

By | Inhaltliches | No Comments

ten-commandment-64x64Die 10 Gebote blicken auf eine bewegte Vergangenheit zurück. Jahrtausende alt und immer noch gültig nicht nur im christlichen Miteinander. Der Überlieferung nach in zwei Tafeln aus Stein gemeißelt (drei bei Mel Brooks) und in der Bundeslade verwahrt, hinter der Indiana Jones her war (und die Schurken im Film auch) und die zuletzt auch in James Frey’s Bestseller „Endgame“ eine Rolle spielte …

Als die zehn Gebote Einzug in das Alte Testament hielten gab es noch keine Softwareentwicklung. Die Leute hatten andere Sorgen.

DocumentingSoftwareArchitecturesNicht ganz so alt (und weniger berühmt) sind die 7 Regeln für gute Dokumentation (im Original: „Seven rules for sound documentation“). Aber immerhin auch schon fünfzehn Jahre. Gedruckt zwischen die zwei Buchdeckel des englischen Standardwerks zu Architekturdokumentation.

Wer von Euch sie zum Beispiel altersbedingt nicht kennt … Kurz zum Kennenlernen — bzw. zur Auffrischung:

1. Write documentation from the point of view of the reader, not the writer.
2. Avoid unnecessary repetition.
3. Avoid ambiguity. Always explain your notation.
4. Use a standard organization.
5. Record rationale.
6. Keep documentation current but not too current.
7. Review documentation for fitness of purpose.

Als das betreffende Buch erschien war der Rational Unified Process ebenso topaktuell wie die UML oder J2EE. Seither ist einiges passiert in der Softwareentwicklung.

Leser1. Schreibe aus Sicht des Lesers. Wiederholung2. Vermeide unnötige Wiederholungen. Hieroglyphen3. Vermeide Mehrdeutigkeit. Erkläre Deine Notation.
Gliederung4. Verwende eine Standardstrukturierung. Begründung5. Halte Begründungen für Entscheidungen fest. Aktualität6. Halte Dokumentation aktuell, aber auch nicht zu aktuell.
Präsentation7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit.

Ich möchte in diesem und zwei weiteren Beiträgen die obigen sieben Regeln im heutigen Licht diskutieren. Können Sie uns heute noch etwas sagen? Oder ist das ganze ein Relikt (dann konservieren wir es mit Lastenheft und Systemtestphase)?

Aus dramaturgischen Gründen gehe ich in einer anderen Reihenfolge vor …

Halte Begründungen fest, oder „Warum solltet Ihr überhaupt dokumentieren?“ (Regel 5)

unknown-documentSimon Brown sagt so schön „Der Quelltext erzählt nicht die ganze Geschichte“. Er steht damit im Kontrast zum beliebten Satz „Der Quelltext ist die Dokumentation“ (… und darüber hinaus dokumentieren wir nichts).

Wenn es um das Festhalten von Informationen geht hat Quelltext Charme. Er ist in jedem Fall erforderlich, das Team versioniert ihn, testet ihn, er ist stets up-to-date. Und tatsächlich kann man dem Quelltext (oder den zugehörigen und gemeinsam versionierten Build-oder Deployment-Skripten) vieles entnehmen. Welche Fremdbibliotheken verwendet werden beispielsweise. Was genau verschweigt der Quelltext?

Einige Informationen lassen sich dem Quelltext zumindest schwierig entlocken. Die Struktur der Lösung beispielsweise, insbesondere wenn es mehrere Zerlegungsideen gibt (technisch in Schichten, fachlich in Komponenten z.B.). Oder wenn Aspekte über die ganze Lösung hinweg einheitlich gelöst sind und es auch bleiben sollen.

Oft macht der Quelltext zwar die Aussage, dass etwas verwendet wird (beispielsweise eine Fremdbibliothek). Aber ob es die Entscheidung des Teams war es zu verwenden, oder eine Vorgabe, das verschweigt der Quelltext bereits. Und im Falle einer Entscheidung des Teams fehlen Informationen zu in Erwägung gezogenen Alternativen, ebenso zu Bewertungskriterien derselben.

Wenn Nachvollziehbarkeit gefragt ist, reicht der Quelltext oft nicht aus. Wenn etwa ein Neuer im Projekt fragt „Warum habt Ihr das so gemacht? Hätte man ja auch anders …“ — da antwortet er nicht. Womit wir direkt bei der nächsten Regel sind.

Schreibe aus Sicht des Lesers (Regel 1)

eyeglasses-of-thin-shapeKlingt vernünftig die Regel, aber beim Nachdenken über Architekturdokumentation wirft sie sofort die Frage auf, wer denn genau dieser Leser ist. Wenn Euch im Team beim besten Willen kein potentieller Interessent für Eure Dokumentation einfällt, solltet Ihr keine schreiben. Dürfte ja keiner merken.

Viele Teams identifizieren jedoch als Zielgruppe sofort den Neuen im Team, oder auch das Entwicklungsteam selbst. Ich mache in Projekten immer sehr Reklame dafür, solche Zielgruppen und deren Informationsbedürfnis (in Form von Zielen) aufzuschreiben. Nicht ausführlich, aber explizit.

Zum Beispiel:

  • Der neue im Team — will sich schnell zurecht finden, zur Lösung beitragen, die Software selber bauen und deployen können …
  • Ein Teammitglied — will Lösungsansätze anderer im Team nachvollziehen können und sich Good Practices abgucken …

Das heißt nicht unbedingt, dass eine Dokumentation diese Ziele ohne Zutun anderer im Team löst. Dokumentation erspart Euch nicht die Kommunikation. Aber: sie unterstützt dabei, d.h. die Sachen, die über den Quelltext hinaus angefertigt werden, helfen beim Erklären.

Und die anderen Regeln?

In zwei Folgebeiträgen hier im Blog führe ich die Diskussion mit den verbliebenen Regeln fort. Ich habe mir ein paar Highlights aufgespart: die Frage nach Redundanz, Aktualität, Notationen …

Wie sehen iSAQB CPSA-Advanced Prüfungsaufgaben eigentlich aus?

By | Allgemein, Inhaltliches | No Comments

diploma-3Der iSAQB-Einstiegslevel Foundation der Certified Professional for Software Architecture-Zertifierung (kurz: CPSA-F) sieht einen Multiple Choice Test als Prüfung vor. Bei der zweiten Stufe, dem Advanced Level, bearbeitet der Prüfling hingegen eine Hausarbeit. Seine Lösung verteidigt er (bzw. sie) dann im Rahmen eines Interviews vor zwei Prüfern, die diese vorher durchgesehen und gegen Kriterien gehalten haben.

Beim Multiple Choice Test (CPSA-F) ist relativ klar, was auf den Prüfling zukommt. Auch wenn einzelne Lernziele mit Ankreuzfragen nur schwer überprüfbar sind, und man sich konkrete Fragen vielleicht nur schwer vorstellen kann, gilt das zumindest für die Form der Prüfung. Zum Advanced-Level höre ich in Workshops oder per Mail dagegen immer wieder die Frage: Wie sieht eine solche Prüfungsaufgabe inhaltlich aus? Das ist nicht unmittelbar klar.

Nun sind die Prüfungsaufgaben selbst natürlich vertraulich (genau wie der Prüfungsfragen im Foundation Level). Vorlagen und Checklisten zur Erstellung von Aufgaben sind jedoch frei zugänglich (auf der Webseite des iSAQB). Sie sind nicht unbedingt leicht verdaulich — falsche Zielgruppe: sie sind für Leute gedacht, die sich neue Aufgaben ausdenken. Ich beschreibe daher im Folgenden mal, wie Aufgaben aufgebaut sind – für Leute, die demnächst ein solche Aufgabe lösen müssen. Was Sie als Advanced-Prüfling also grob erwartet…

Überblick Prüfungsaufgabe

Wie sieht eine Aufgabe grundsätzlich aus?

Die Aufgabenstellung einer Prüfungsaufgabe für CPSA-Advanced umfasst mindestens 10 Seiten und höchstens 25 (siehe Abbildung rechte, die Seitenzahlen sind Beispielwerte).

Jede Aufgabe ist einer Systemart zugeordnet. Aktuell sind das

  • Informationssystem
  • Embedded System
  • Websystem

Ein Kandidat gibt bei der Anmeldung zur Prüfung die gewünschte Systemart an und erhält dann eine Aufgabe aus diesem Bereich. Damit soll verhindert werden, dass ein Prüfling mit einer Umfeld konfrontiert wird. das ihm völlig fremd ist. Darüber hinaus ermöglicht ein kurzer Abstract (2-3 Sätze) zur Aufgabenstellung dem Prüfling zu entscheiden, ob die Aufgabe grob passt.

Jede Aufgabe selbst zerfällt dann in zwei grobe Blöcke: Ein Fallbeispiel in Form inhaltlicher Inputs, und die Aufgabenstellung selbst. Letztere ist in Teilaufgaben gegliedert. Die konkreten Prüfungsaufgaben variieren dabei in der Zusammenstellung der inhaltlichen Inputs und den Teilaufgaben.

Das Fallbeispiel

Prüfungsaufgaben: FallbeispielBeim Fallbeispiel handelt es sich um ein fiktives Projekt, eine Produktentwicklung, eine Migration oder ähnliches. Nach einem kurzen Überblick liegen konkrete Informationen dazu in Form inhaltlicher Inputs vor. Im Wesentlichen sind das Anforderungen, die der Prüfling in den späteren Teilaufgaben berücksichtigen muss. Denkbar sind etwa folgende Inhalte:

  • Funktionale Anforderungen (z.B. wichtige Use Cases, User Stories, …)
  • Qualitätsziele, ggf. verfeinert in Szenerien
  • Stakeholder (z.B. Liste, Personas)
  • Interviews mit Stakeholdern
  • Technische und/oder organisatorische Rahmenbedingungen
  • Fachlicher Kontext, Benutzer und Fremdsysteme
  • Normen und Konventionen
  • Risiken

Nicht jede Aufgabenstellung enthält dabei alle diese Inhalte. Weiterhin kann es sein, dass bestimmte Anforderungen explizit genannt sind, andere jedoch im Rahmen der Aufgabe erarbeitet werden müssen. Beispielsweise liegen Interviews mit Stakeholdern vor, und die Rahmenbedingungen oder Qualitätsziele muss der Prüfling dann im Rahmen einer Teilaufgabe herausarbeiten und ggf. priorisieren.

Ihre Aufgabe

Prüfungsaufgaben: TeilaufgabenGanz ähnlich wie das Fallbeispiel mit seinen inhaltlichen Inputs ist auch die Aufgabe unterteilt — in mindestens 5 und maximal 10 Teilaufgaben, die unterschiedliche Aspekte der Architekturarbeit abdecken. In Summe soll die Bearbeitung zeigen, dass der Prüfling in der Lage ist, aus Anforderungen methodisch eine Architektur zu entwerfen und festzuhalten, sie zu reflektieren und zu kommunizieren. Analog zu den denkbaren Inputs oben beim Fallbeispiel hier mögliche Teilaufgaben:

  • Kontext abgrenzen
  • Qualitätsziele identifizieren, Qualitätsbaum und -szenarien erarbeiten
  • Offene Fragen an Stakeholder formulieren
  • Lösungsstrategie/Architekturvision anfertigen
  • Architekturentscheidungen treffen
  • Technische Fragestellung inkl. Alternativen und Begründung bearbeiten
  • System strukturieren, fachlich zerlegen, Verantwortlichkeiten festlegen
  • Schnittstellen entwerfen
  • technische und/oder übergreifende Aspekte bearbeiten
  • Lösung qualitativ bewerten
  • Risiken identifizieren und adressieren

Es gibt dabei Überschneidungen in inhaltlichen Inputs und Teilaufgaben: Der Systemkontext könnte etwa mit dem Fallbeispiel gegeben sein (als inhaltlicher Input) oder muss alternativ als Teilaufgabe erarbeitet werden.
Prüfungsaufgaben: FAQ

Häufige Fragen zu Prüfungsaufgaben

Wie wird sichergestellt, dass die Aufgabe zu den von mir besuchten Schulungen passt?

Eigentlich gar nicht. Durch die Angabe der Systemart (z.B. Web, Embedded) wird lediglich abgesichert, dass es technologisch grob passt. Ansonsten sind die Aufgaben nicht an bestimmte Module gebunden. Die Teilaufgaben (+ Interview) decken lediglich die drei Kompetenzbereiche („Säulen“) des Advanced-Levels ab.

Welchen Umfang hat meine Lösung?

Sie halten Ihre Lösung auf maximal 40 DIN A4-Seiten (inklusive Abbildungen) fest. Dazu haben Sie maximal 3 Monate Zeit (Details siehe Prüfungsordnung). Vom Aufwand sind die Teilaufgaben so bemessen, dass ein Prüfling sie in 40 Stunden erledigen kann.

Was wenn Technologien oder Methoden gefordert sind, die ich nicht beherrsche?

Die Aufgabenstellungen lassen Ihnen angemessenen Spielraum bezüglich Technologien, Werkzeugen, Notation und Ähnlichem. Wenn etwas explizit gefordert ist, so ist sichergestellt, dass Informationen dazu frei zugänglich sind. Entweder es liegt der Aufgabe bereits in den inhaltlichen Inputs oder in einem Anhang bei, oder es wird darauf verwiesen. Es kann natürlich vorkommen, dass Sie sich zur Lösung der Aufgabe noch Wissen aneignen müssen.

Was wenn mir die gegebenen Anforderungen zur Lösung nicht ausreichen?

Wie im richtigen Leben kann es sein, dass Ihnen zur Lösung der Aufgabe Informationen fehlen. Im Einzelfall scheinen sich Anforderungen sogar zu widersprechen (beispielsweise Aussagen in Interviews von Stakeholdern mit unterschiedlichen Prioritäten). Normalerweise klären sie das im Projekt mit den Beteiligten, finden Kompromisse, etc. Da Ihnen die Leute im Rahmen Ihrer Hausaufgabe nicht zur Verfügung stehen, treffen Sie Annahmen. Diese kennzeichnen Sie in Ihrer Lösung explizit als solche. Achten Sie darauf, dass diese sinnvoll und konsistent untereinander und zur Aufgabenstellung sind.

Weitere Informationen

Ich hoffe, ich konnte einen Eindruck vermitteln, wie die Prüfungsaufgaben im CPSA-Advanced-Level grundsätzlich aussehen. Wenn Sie Fragen zu dem Thema haben, kommen Sie gerne auf mich zu. Ansonsten: Auf der iSAQB-Seite finden Sie vieles rund um den Advanced-Level. Hier noch ein paar weiterführende Links …

ISO, weshalb warum? Ist Software-Qualität Geschmackssache?

By | Inhaltliches | No Comments

Wir tun uns leicht damit, etwas nach unserem persönlichen Geschmack zu bewerten, zum Beispiel Musik. Auch bei Software äußern wir schnell unsere Meinung über eine Lösung: „Das hätte ich anders gemacht!“ oder „So tut das nicht!“
Für die Einschätzung der Qualität von Softwaresystemen reicht dies jedoch nicht aus. Das stellen Teams dann fest, wenn es unterschiedliche Meinungen zu einer Lösung gibt. Wer hat nun Recht? Derjenige, der länger im Team ist? Der mit mehr allgemeiner Erfahrung? Schnell wird klar, dass der persönliche Maßstab nicht ausreichend ist und wir einen allgemeinen Maßstab benötigen um sinnvoll bewerten zu können, ob eine Lösung geeignet ist.

FURPS/FURPS+, DIN 66272, ISO 9126, ISO 25010, etc.

Bevor wir uns selbst etwas überlegen, greifen wir doch lieber auf eins der bestehenden Modelle für Qualität von Softwaresystemen zurück. Für Softwarearchitekten sind diese Modelle deshalb interessant, weil die qualitativen Anforderungen wichtige Treiber für Architekturarbeit sind. Aus der Aufnahme und Bewertung dieser Anforderungen leite ich ab, in welchen Bereichen ich schon sicher bin und in welchen Bereichen meines Entwurfs ich noch investieren muss.

Alle Modelle definieren Software-Qualität anhand von Merkmalen, die am fertigen System sichtbar werden. Sie unterscheiden sich in der Auswahl und Beschreibung der Merkmale. Am besten lässt sich das anhand der am weitesten verbreiteten Modelle zeigen, der ISO 9126 und der ISO 25010. Letztere ist die Ablösung der erstgenannten Norm und setzt sich erst nach und nach in der Literatur durch. Sie treffen daher häufig noch auf die ältere Norm.

Als Überblick folgt die Auflistung und Beschreibung der unterschiedlichen Qualitätsmerkmale der ISO 25010 im Einzelnen:

Qualitätsmerkmal Englischer Begriff Beschreibung Unterkategorien
Funktionalität
Funktionalität
Functional Suitability Die Art und Weise, wie die gewünschte Funktionalität geliefert wird Vollständigkeit, Korrektheit, Angemessenheit
Effizienz
Effizienz
Performance Efficiency Stellt die Leistung des Systems in Relation zum Ressourcenverbrauch dar
Häufig auch mit Performance bezeichnet
Zeitverhalten, Ressourcenverbrauch, Kapazität
Kompatibilität
Kompatibilität
Compatibility Fähigkeit zum Austausch von Daten mit anderen Systemen oder Komponenten, die auf anderer oder der gleichen Hardware laufen. Ko-Existenz, Interoperabilität
Benutzbarkeit
Benutzbarkeit
Usability Grad der Nutzbarkeit für definierte Benutzer, vorher bestimmte Ziele mit dem System effizient und zufrieden zu erreichen. Erlernbarkeit, Bedienbarkeit,
Schutz vor Fehlern des Benutzers, Barrierefreiheit
Zuverlässigkeit
Zuverlässigkeit
Reliability Erbringung der Leistungen des Systems unter bestimmten Bedingungen über einen definierten Zeitraum Reife,
Verfügbarkeit, Fehlertoleranz, Wiederherstellbarkeit
Sicherheit
Sicherheit
Security Fähigkeit, die Daten und das System so zu schützen, dass sowohl beabsichtigte als auch unbeabsichtigte Zugriffe erkannt und abgewehrt werden Vertraulichkeit,
Integrität, Nachweisbarkeit,
Ordnungsmäßigkeit, Authentizität
Wartbarkeit
Wartbarkeit
Maintainability Die Wirtschaftlichkeit, mit der ein System angepasst werden kann, um auf Veränderungen der Umwelt, Rahmenbedingungen oder Anforderungen zu reagieren sowie Fehler zu korrigieren Modularität, Wiederverwendbarkeit, Analysierbarkeit, Änderbarkeit, Testbarkeit
Portabilität
Portabilität
Portability Einfachheit, mit der ein System von einer Umgebung auf eine andere übertragen werden kann Anpassbarkeit, Installierbarkeit,
Austauschbarkeit

Die entscheidende Neuerung bei der ISO 25010 – auch unter dem Namen SQuaRE (Systems and Software Quality Requirements and Evaluation) bekannt – ist die Hinzunahme von Sicherheit und Kompatibilität als Hauptkategorien, die seit der Definition der ISO 9126 an Bedeutung hinzugewonnen haben. Interessant dabei ist, dass Sicherheit in der alten Norm noch eine Unterkategorie zu Funktionalität war, also sozusagen befördert wurde. Insgesamt erhalten wir damit ein vollständiges Modell zur Bewertung von Software-Qualität.

Das im englischsprachigen Raum weit verbreitete FURPS+ setzt sich aus zwei Bestandteilen zusammen: Die fünf Qualitätsmerkmale Funktionalität, Benutzbarkeit, Zuverlässigkeit, Effizienz und Änderbarkeit (der Name des Modells ist aus den Anfangsbuchstaben der englischen Begriffe abgeleitet) und dazu Rahmenbedingungen für Design, Entwicklung, Schnittstellen und Hardware. Die einzuhaltenden Rahmenbedingungen beeinflussen nämlich die Erreichung der Qualitätsziele mitunter stark. Auch bei der Verwendung von anderen Modellen müssen Projekte diese natürlich berücksichtigen.

Software-Qualität detaillierter erklärt

Die Unterkategorien helfen, die Bedeutung der Begriffe genauer einzuordnen. Zum Beispiel enthält der Begriff Effizienz neben dem offensichtlichen Zeitverhalten eben auch den Ressourcenverbrauch. Für Ihr Softwareprojekt bedienen Sie sich dieser Kategorien und nehmen auch eigene Begriffe hinzu, die in Ihrem Umfeld gebräuchlicher sind. Für eine Konkretisierung der Anforderungen an Ihr System benutzen wir sogenannte Qualitätsszenarien. Diese stellen das System in den Mittelpunkt und zeigen dessen Verwendung durch einen Akteur. Dieser kann neben dem Benutzer auch jemand aus dem Entwicklungs- oder Betriebsteam sein oder auch ein Fremdsystem. In einem weiteren Blogpost zeige ich, wie Qualitätsszenarien genau aussehen und gebe Beispiele für die aufgeführten Qualitätsmerkmale. Mit Merkmalen und dazugehörigen Szenarien erhalten Sie ein rundes Bild über die von Ihrem System gewünschte Qualität.

Auch wenn wir nun ein Modell gefunden haben, mit dem wir Software-Qualität bewerten können, rate ich davon ab, damit verschiedene Systeme untereinander zu vergleichen: Die Anforderungen für die Lösungen unterscheiden sich ebenso wie die Umfelder, in denen sie entwickelt werden. Verschiedene Lösungsalternativen für ein System können wir damit aber sehr gut vergleichen und die Aussage „So tut das nicht!“ beweisen oder widerlegen.