Schlagwort-Archiv: Automatisierung
Inhalt | Apache Maven [de]
Referenzen & Literatur
Kochbuch: Maven Codebeispiele
Antworten
In unserem Git Repository befindet sich eine umfangreiche Sammlung an verschiedenen Codebeispielen für Apache Maven Projekte. Alles gut übersichtlich nach Themengebieten sortiert.
Zurück zum Inhaltsverzeichnis: Apache Maven Master Class
- Token Replacement
- Compiler Warnings
- Excecutable JAR Files
- Enforcments
- Unit & Integration Testing
- Multi Module Project (JAR / WAR)
- BOM – Bill Of Materials (Dependency Management)
- Running ANT Tasks
- License Header – Plugin
- OWASP
- Profiles
- Maven Wrapper
- Shade Ueber JAR (Plugin)
- Java API Documantation (JavaDoc)
- Java Sources & Test Case packaging into JARs
- Docker
- Assemblies
- Maven Reporting (site)
- Flatten a POM
- GPG Signer
Apache Maven Master Class
Apache Maven (kurz Maven) erschien erstmalig am 30. März 2002 als Apache Top Level Projekt unter der freien Apache 2.0 Lizenz. Diese Lizenz ermöglicht auch eine freie Nutzung für Unternehmen im kommerziellen Umfeld ohne das Lizenzgebühren fällig werden.
Das Wort Maven kommt aus dem Jiddischen und bedeutet so viel wie „Sammler des Wissens“.
Maven ist ein reines Kommandozeilenprogramm und wurde in der Programmiersprache Java entwickelt. Es gehört in die Kategorie der Build-Werkzeuge und findet vornehmlich in Java Softwareentwicklungsprojekten Verwendung. In der offiziellen Dokumentation bezeichnet sich Maven als Projektmanagement-Werkzeug, da die Funktionen weit über das Erstellen (Kompilieren) der binär ausführbaren Artefakte aus dem Quellcode hinausgehen. Mit Maven können Qualitätsanalysen von Programmcode und API-Dokumentationen erzeugt werden, um nur einige der vielfältigen Einsatzgebiete zu nennen.
Vorteile
- Zugriff auf alle Abonnementartikel
- Zugriff auf das Maven Sample Git Repository
- regelmäßige Updates
- E-Mail Support
- regelmäßige Live Video FAQ
- Video Workshops
- einreichen eigener Themenvorschläge
- 30% Rabatt auf Maven Schulung
Online Kurs (Jahres Abo / 365 Tage)
Maven Master Class
m 3.47 Milli-Bitcoin
Zielgruppen
Dieser Onlinekurs eignet sich sowohl für Anfänger ohne Vorkenntnisse, als auch für erfahrene Experten. Jede Lektion ist in sich geschlossen und kann individuell ausgewählt werden. Umfangreiches Zusatzmaterial erklärt Zusammenhänge und ist mit zahlreichen Referenzen unterlegt. Das ermöglicht Ihnen den Kurs Apache Maven Master Class auch als Nachschlagewerk zu nutzen. Kontinuierlich werden dem Kurs neue Inhalte hinzugefügt. Wenn Sie sich für eine Mitgliedschaft der Apache Maven Master Class entscheiden sollten, haben Sie außerdem vollen Zugriff auf exklusive Inhalte.
Entwickler
- Maven Grundlagen
- Maven auf der Kommandozeile
- IDE Integration
- Archetypes: Projektstrukturen anlegen
- Testintegration (TDD & BDD) mit Maven
- Testcontainers mit Maven
- Multi Module Projekte für Microservices
Buildmanager / DevOps
- Release Management mit Maven
- Deploy nach Maven Central
- Sonatype Nexus Repository Manager
- Maven Docker Container
- Docker Images mit Maven erstellen
- verschlüsselte Passwörter
- Prozess & Build Optimierung
Qualitätsmanager
- Maven Site – Die Reporting Engine
- Testabdeckung ermitteln & bewerten
- statische Codeanalyse
- Codingstyle Vorgaben überprüfen
Featureitis
Man muss nicht gleich Softwareentwickler sein, um ein gutes Anwendungsprogramm erkennen zu können. Doch aus eigener Erfahrung ist es mir oft passiert, dass Programme, die zu Beginn vielversprechend und innovativ waren, ab einer ‚gewissen‘ Nutzerzahl zu unhandlichen Boliden mutiert sind. Da ich diese Beobachtung nun schon einige Jahrzehnte regelmäßig aufs Neue mache, habe ich mich gefragt, woran das wohl liegen kann.
Das Phänomen, dass Softwareprogramme oder Lösungen im Allgemeinen mit Details überladen werden, hat Brooks in seinem Klassiker ‚The Mythical Man-Month‘ als Featuritis bezeichnet. Wenn man überlegt, dass die Erstausgabe des Buches im Jahr 1975 erschienen ist, kann man wohl von einem lange bekannten Problem sprechen. Das wohl bekannteste Beispiel für Featuritis ist das Betriebssystem Windows von Microsoft. Natürlich gibt es noch unzählige andere Beispiele für Verschlimmbesserungen.
Windowsnutzer, die bereits Windows XP kannten und dann mit dem tollen Nachfolger Vista konfrontiert wurden, um dann mit Windows 7 wieder besänftigt zu werden, um mit 8 und 8.1 beinahe einen Herzinfarkt erlitten zu haben, sich zu Beginn von Windows 10 wieder beruhigen. Jedenfalls für kurze Zeit, bis der Updatezwang für schnelle Ernüchterung sorgte. Von Windows 11 ganz zu schweigen. Zu Windows hieß es einmal, jede zweite Version ist Schrott, die sollte man überspringen. Nun ja, das stimmt seit Windows 7 schon lange nicht mehr. Für mich war Windows 10 dann der ausschlaggebende Punkt, vollständig auf Microsoft zu verzichten, und ich habe mir wie viele andere auch ein neues Betriebssystem zugelegt. Einige sind zu Apple gewechselt, und wer sich die teure Hardware nicht leisten kann oder will, hat wie ich auf ein Linuxsystem gesetzt. Hier zeigt sich, wie Uneinsichtigkeit schnell zum Verlust signifikante Marktanteile führt. Da Microsoft aus diesen Entwicklungen keine Konsequenzen zieht, scheint dem Unternehmen dieser Umstand weniger wichtig zu sein. Andere Unternehmen wiederum kann so etwas schnell an den Rand der Existenz bringen, und darüber hinaus.
Eine Motivation, immer mehr Funktionen in eine bestehende Anwendung zu bringen, ist der sogenannte Produktlebenszyklus, der durch die BCG Matrix in Abbildung 1 dargestellt wird.
Mit der Einführung ist noch nicht sicher, ob das Produkt vom Markt akzeptiert wird. Wenn es die Nutzer annehmen, steigt es schnell zum Star auf und erreicht seine maximale Marktposition als Cash Cow. Sobald die Sättigung überschritten wurde, degradiert es zum Ladenhüter. Soweit, so gut. Leider herrscht im Management überwiegend die Idee, dass, wenn kein Wachstum zum vorherigen Quartal mehr erzeugt wird, die Sättigung bereits überschritten wurde. So kommt es zu der sinnbefreiten Annahme, den Nutzern müsste jedes Jahr eine aktualisierte Version des Produktes aufgedrängt werden. Die Motivation zu kaufen gelingt natürlich nur, wenn eine dickgefüllte Featureliste an Neuerungen auf die Verpackung gedruckt werden kann.
Da sinnvoll konzipierte Funktionen sich aber nicht wie am Fließband aus dem Ärmel schütteln lassen, kommt auch jedes Mal gleich ein Redesign der grafischen Benutzeroberfläche als Gratis-Schmankerl mit dazu. Schließlich hat man dann das Gefühl, man habe etwas völlig Neues, weil man erst wieder eine Eingewöhnung braucht, um die neue Platzierung alt bekannter Funktionen zu entdecken. Es ist ja nicht so, dass das Redesign in der Benutzung Wege verkürzen würde und die Produktivität erhöht. Die Zusammenstellung der Eingabemasken und Schaltflächen erscheint jedes Mal willkürlich zusammengewürfelt.
Aber keine Sorge, ich will nicht zum Updateboykott aufrufen, sondern einmal darüber sprechen, wie man es besser machen kann. Denn eines sei gewiss: Dank künstlicher Intelligenz wird sich der Markt für Softwareprodukte in wenigen Jahren massiv verändern. Ich erwarte nicht, dass komplexe und spezialisierte Anwendungsprogramme in absehbarer Zeit durch KI-Algorithmen produziert werden. Allerdings erwarte ich, dass in diesen Anwendungsprogrammen genügend KI generierte schlechte Codesequenzen, die der Entwickler nicht versteht, in die Codebasis eingebracht werden, was zu unstabilen Anwendungen führen wird. Diese Überlegung ist für mich ein Grund, wieder über saubere, handgemachte, leitungsfähige und verlässliche Software nachzudenken, denn ich bin mir sicher, dass dafür immer ein Markt bestehen bleiben wird.
Ich möchte einfach keinen Internetbrowser, der zu einer Kommunikationszentrale mutiert ist und neben dem eigentlichen Anzeigen von Internetseiten noch Chat, E-Mail, Kryptobezahlmethoden und was weiß ich noch alles enthält. Ich möchte, dass mein Browser schnell startet, wenn ich irgendetwas klicke, dann schnell reagiert und die Inhalte der Internetseiten korrekt und schnell darstellt. Sollte ich einmal den Wunsch haben, etwas anderes mit meinem Browser zu tun, wäre es nett, wenn ich dies aktiv durch ein Plug-in aktivieren kann.
Nun gibt es zu dieser gerade beschriebenen Problemstellung oft die Argumentation, dass man ja mit den vielen Funktionen einen breiten Nutzerkreis erreichen möchte. Gerade wenn eine Anwendung zu Beginn alle möglichen Optionen auch aktiv eingeschaltet hat, holt das schnell den unkundigen Benutzer ab, der dann nicht erst begreifen muss, wie sein Programm überhaupt funktioniert. Ich kann diese Überlegung durchaus nachvollziehen. Es ist auch völlig in Ordnung, wenn ein Hersteller sich ausschließlich auf unkundige Anwender konzentriert. Es gibt aber einen Mittelweg, der alle Nutzergruppen gleichmäßig berücksichtigt. Diese Lösung ist auch nicht neu und sehr gut bekannt, die sogenannten Produktlinien.
In der Vergangenheit haben Hersteller immer Zielgruppen wie Privatpersonen, Unternehmen und Experten definiert. Diesen Nutzergruppen wurden dann oft Produktbezeichnungen wie Home, Enterprise und Ultimate zugeordnet. Das führte dazu, dass jeder die Ultimate Version wollte. Das Phänomen nennt sich Fear Of Missing Out (FOMO), also etwas zu verpassen. Deswegen sind die Bezeichnungen der Produktgruppen und deren zugeordneten Funktionen psychologisch ungeschickt gewählt. Wie kann man das also besser machen?
Ein Experte konzentriert sich bei seiner Arbeit auf spezielle Basisfunktionen, mit denen er seine Aufgaben schnell und ohne Ablenkung erledigen möchte. Das impliziert für mich Begriffe wie Essentials, Pure oder Core als Produktline.
Wenn das Produkt dann noch im Unternehmen von mehreren Personen verwendet werden soll, benötigt dies oft zusätzliche Funktionen wie zum Beispiel ein externes Benutzermanagement, wie LDAP oder IAM. Diese spezialisierte Produktlinie assoziiert Begriffe wie Enterprise (verbrannt), Company, Business und so weiter.
Das zugemüllte Endergebnis, das eigentlich für NOOPS gedacht ist und alle möglichen Sachen bereits über die Installation aktiviert hat. Wenn den Leuten die Zeit, bis die Anwendung gestartet ist und sie reagiert, egal ist, dann nur zu. Immer in die Vollen. Rein, was rein geht! Hier eignen sich Bezeichnungen wie Ultimate, Full und Maximized Extended als Bezeichnung der Produktlinie. Wichtig ist nur, dass die Profis erkennen, dass es sich um die zugemüllte Variante handelt.
Wer nun geschickt mit diesen Produktlinien spielt und möglichst alle Funktionen über sogenannte Module bereitstellt, die nachinstallierbar sind, ermöglicht eine hohe Flexibilität auch im Expertenmodus, denen durchaus die eine oder andere Zusatzfunktion genehm ist.
Installiert man auf das Modulsystem zuvor noch ein Tracking, um festzustellen, wie professionelle Anwender ihre Version upgraden, dann hat man schon eine gute Idee, was in die neue Version von Essentials hinzugefügt werden könnte. Bei dem Tracking sollte man sich aber nicht auf die Downloads als Entscheidungskriterium stützen. Ich selbst probiere oft Dinge aus und lösche Erweiterungen auch schneller, als der Installationsprozess gedauert hat, wenn ich der Meinung bin, dass diese nutzlos sind.
Ich möchte zu der gerade beschriebenen Problematik ein kleines Beispiel geben, das aus dem DevOps Bereich stammt. Zum einen gibt es das bekannte GitLab, das ursprünglich einmal ein reines Code Repository-Hosting-Projekt gewesen ist. Darauf deutet auch der Name, bis heute. Eine Anwendung, die auf einem Server bereits 8 GB RAM in der Basis-Installation benötigt, um ein Git Repository für andere Entwickler erreichbar zu machen, ist für mich unbrauchbar, denn diese Software wurde über die Zeit zur EierlegendenWollmilchSau. Langsam, unflexibel und mit allem Kram zugemüllt, der über Speziallösungen besser umgesetzt wurde.
GitLab gegenüber steht eine andere Lösung namens SCM-Manager, die weniger bekannt ist und sich ausschließlich auf das Bereitstellen der Code Repositories konzentriert. Ich selbst nutze und empfehle den SCM-Manager, weil er mit der Basis-Installation extrem kompakt ist. Aber dennoch gibt es eine gigantische Funktionsvielfalt, die man über Plug-ins nachrüsten kann.
Für mich sind Lösungen, die eine All In One Solution bereitstellen wollen, eher suspekt. Das ist für mich immer gleich dem Motto: alles und nichts. Es gibt keine EierlegendeWollMilchSau oder wie man in Österreich zu sagen pflegt, keinen Wunderwuzzi!
Wenn ich Programme für meinen Arbeitsprozess auswähle, orientiere ich mich ausschließlich an deren Kernfunktionalität. Sind die Grundeigenschaften, die das Marketing verspricht, wirklich vorhanden und möglichst intuitiv nutzbar? Gibt es eine aussagekräftige Dokumentation, die über ein bloßes ‚Hallo Welt‘ hinausgeht? Konzentriert man sich darauf, die Kernfunktionen stets zu optimieren, und berücksichtigt neue innovative Konzepte? Das sind Fragen, die für mich relevant sind.
Gerade im kommerziellen Umfeld werden oft Programme eingesetzt, die nicht halten, was das Marketing verspricht. Man wählt nicht aus, was man tatsächlich für die Erledigung der Aufgaben benötigt, sondern Anwendungen, deren Beschreibung mit sogenannten Buzzwords vollgestopft ist. Deswegen glaube ich, dass Unternehmen, die sich wieder auf die Kernkompetenzen fokussieren und dazu hoch spezialisierte Anwendungen nutzen, die Gewinner von morgen sind.
Von Missmanagement und Alpha-Geeks
Als ich neulich das Buch „The Manager’s Path“ von Camille Fournier in die Hand bekam, war ich recht schnell an Tom DeMarco erinnert. Dieser hat den Klassiker „Peopleware“ geschrieben und Anfang 2000 das Buch „Adrenalin Junkies und Formular Junkies“ veröffentlicht. Eine Liste an Stereotypen, die man in Softwareprojekten antreffen kann, mit Hinweisen, wie man mit ihnen umgeht. Nach einigen Jahrzehnten im Geschäft kann ich jedes einzelne Wort aus eigener Erfahrung bestätigen. Und es ist auch heute noch immer ein Thema, denn Menschen machen nun einmal Projekte und wir alle haben so unsere Eigenheiten.
Damit Projekte erfolgreich verlaufen, müssen nicht nur technische Herausforderungen gemeistert werden. Auch zwischenmenschliche Beziehungen spielen eine wesentliche Rolle für deren Erfolg. Ein wichtiger Faktor in diesem Zusammenhang, der oft wenig Beachtung findet, ist die Projektleitung. Es gibt Regale voller hervorragender Literatur, wie man ein guter Manager werden kann. Das Problem ist leider, dass nur wenige, die diese Position besetzen, diese nicht ausfüllen und noch weniger Interesse besteht, die eigenen Fertigkeiten weiterzuentwickeln. Das Ergebnis von schlechtem Management sind aufgeriebene und gestresste Teams, extremer Druck im Tagesgeschäft und oft auch Verzug von Lieferterminen. Da braucht man sich auch nicht wundern, wenn dies Auswirkungen auf die Qualität des Produktes hat.
Einer der ersten Sprüche, den ich in meinem Berufsleben gelernt habe, war: Wer glaubt, dass ein Projektleiter Projekte leitet, der glaubt auch, dass ein Zitronefalter Zitronen faltet. Es scheint also eine sehr alte Weisheit zu sein. Was ist aber das wirkliche Problem bei schlechtem Management? Jeder, der eine Stelle für einen Manager zu besetzen hat, ist in der Pflicht, dessen Fertigkeiten und charakterliche Eignung auf Herz und Nieren zu prüfen. Hier lässt man sich schnell von inhaltslosen Floskeln und einer Liste großer Namen in der Branche in der Vita beeindrucken, ohne die tatsächliche Leistung zu hinterfragen. In meiner Erfahrung bin ich vornehmlich auf Projektleiter gestoßen, die oft nicht die notwendigen fachlichen Kenntnisse hatten, um wichtige Entscheidungen zu treffen. Nicht selten wurde ich in IT-Projekten von Managern mit den Worten „Ich bin kein Techniker, macht das unter euch aus.“, abgefertigt. Das ist natürlich fatal, wenn die Person, welche die Entscheidungen treffen soll, diese nicht treffen kann, weil das notwendige Wissen fehlt. Ein Manager im IT-Projekt muss natürlich nicht wissen, welcher Algorithmus schneller terminiert. Hierfür gibt es die Möglichkeit von Evaluierungen, als Grundlage von Entscheidungen. Aber ein Grundverständnis der Programmierung sollte vorhanden sein. Wer nicht weiß, was eine API ist und wieso Module, die später zu einer Software zusammengesetzt werden sollen, durch Versionskompatibilitäten nicht zusammenarbeiten, hat keine Berechtigung, sich als Entscheidungsträger aufzuspielen. Ein Grundverständnis über die Prozesse in der Softwareentwicklung und die verwendeten Programmierparadigmen ist auch für Projektleiter, die nicht am Code arbeiten, unumgänglich.
Ich plädiere daher dafür, dass man nicht nur die Entwickler, die man einstellt, auf ihre Fertigkeiten hin prüft, sondern auch die Manager, die in ein Unternehmen aufgenommen werden sollen. Für mich ist ein absolutes No Go bei der Auswahl meiner Projekte, ein externes Projektmanagement. Das führt in aller Regel nur zu Chaos und Frustration bei allen beteiligten Personen, weswegen ich solche Projekte ablehne. Manager, die nicht ins Unternehmen eingebunden sind und deren Leistung nach dem Erfolg von Projekten bewertet wird, liefern erfahrungsgemäß keine saubere Arbeit ab. Zudem können interne Manager, ebenso wie die Entwickler, durch Mentoring, Trainings und Workshops ihre Fertigkeiten entwickeln und weiter ausbauen. Das Ergebnis sind ein gesundes, entspanntes Arbeitsklima und erfolgreiche Projekte.
Der Titel dieses Artikels weist auf toxische Stereotypen im Projekteschäft hin. Ich bin mir sicher, jeder ist auf den ein oder anderen Stereotypen bereits im beruflichen Umfeld getroffen. Es wird viel diskutiert, wie man mit diesen Zeitgenossen umgehen soll. Ich möchte aber anmerken, dass kaum jemand als „Monster“ geboren wurde. Dass Menschen so sind, wie sie sind, ist das Resultat ihrer Erfahrungen. Lernt ein Kollege, dass er, wenn er gestresst ausschaut und immer hektisch wirkt, als guter Arbeiter wahrgenommen wird, perfektioniert er dieses Verhalten über die Zeit.
Camille Fournier hat es mit dem Begriff „The Alpha Geek“ sehr auf den Punkt gebracht. Jemand, der seine Rolle im Projekt unersetzlich gemacht hat und auf alles eine Antwort hat. Meist verächtlich auf die Kollegen herabschaut, aber nie eine Aufgabe wirklich ohne Nacharbeiten anderer sauber zu Ende bringen kann. Unrealistische Abschätzungen für umfangreiche Aufgaben sind ebenso typisch wie die Relativierung komplexer Sachverhalte. Natürlich ist das der Liebling aller Projektleiter, die sich wünschen, das ganze Team würde aus diesen „Alpha Geeks“ bestehen. Ich bin mir sehr sicher, wenn dieser Traum wahr werden könnte, es die optimale Strafe für die Projektleiter wäre, die solche Menschen erst möglich machen.
Damit man sich im eigenen Unternehmen keine „Alpha Geeks“ züchtet, ist es notwendig, keinen Personenkult zu etablieren und die persönlichen Favoriten gegenüber dem restlichen Team zu überhöhen und auf ein Podest zu stellen. Natürlich ist es auch unabdingbar, stets die Arbeitsergebnisse zu hinterfragen. Wer eine Aufgabe als erledigt markiert und diese Nacharbeiten erfordert, sollte diese Nacharbeiten stets erneut zugewiesen bekommen, bis das Ergebnis zufriedenstellend ist.
Ich persönlich habe die selbe Auffassung wie Tom DeMarco, was die Dynamiken eines Projektes betrifft. Die Produktivität kann man zwar über die Menge der erledigten Aufgaben bewerten, dennoch gibt es auch noch weitere Einflüsse, die eine wichtige Rolle spielen. So habe ich durch meine Erfahrung die Auffassung, dass man, wie bereits erwähnt, sehr viel Wert darauf legen sollte, dass Mitarbeiter die begonnenen Aufgaben sauber und vollständig lösen, bevor sie eine neue Aufgabe annehmen. Kollegen, die eine bestimmte Aufgabe „kleinreden“ und zu geringe, unrealistische Einschätzungen abgeben, genau diese Aufgabe übernehmen. Zudem gibt es auch Kollegen, die zwar einen recht geringen Output haben, dafür aber sehr viel für die Harmonie im Team beitragen.
Wenn ich über Menschen spreche, die ein gesundes Team formen, meine ich damit nicht jeden Tag Süßigkeiten hinzustellen. Es geht um die, die durchaus gute Fähigkeiten haben und diese als Mentor anderen Kollegen beibringen. Meist haben diese Personen einen guten Stand im Team und ihnen wird viel Vertrauen entgegengebracht, weswegen sie auch oft als Mediatoren bei Konflikten gute Ergebnisse erzielen. Es sind nicht die Menschen, die durch falsche Versprechen versuchen, everybodys Darling zu sein, sondern die, die zuhören und sich Zeit nehmen, eine Lösung zu finden. Sie sind oft das Mädchen für alles und haben nicht selten ein ruhiges, unscheinbares Auftreten. Da sie Lösungen haben und oft eine helfende Hand reichen, haben sie selbst eine mittelmäßige Bewertung ihrer Leistung in den typischen Prozessmetriken. Ein guter Manager erkennt diese Personen rasch, weil auf sie in aller Regel Verlass ist. Sie sind ausgeglichen und wirken wenig gestresst, weil sie mit Ruhe und Kontinuität vorgehen.
Natürlich kann man über die Stereotypen in einem Softwareprojekt noch viel mehr sagen, aber ich denke, die bereits getroffenen Ausführungen geben ein gutes Grundverständnis über das, was ich zum Ausdruck bringen möchte. Denn ein erfahrener Projektleiter kann viele der beschriebenen Probleme bereits während ihrer Entstehung wieder abstellen. Dazu gehören natürlich auch solides technisches Wissen und etwas Menschenkenntnis.
Es muss uns natürlich auch bewusst sein, dass erfahrene Projektleiter nicht einfach so da sind. Man muss sie genau wie die Mitglieder eines Teams entwickeln und fördern. Dazu gehört durchaus auch die Rotation durch alle technischen Abteilungen wie Entwicklung, Test und Betrieb. Dazu eignen sich Paradigmen wie Pairprogramming hervorragend. Denn es geht nicht darum, aus einem Manager einen Programmierer oder Tester zu machen, sondern ihm oder ihr ein Verständnis der täglichen Abläufe zu verschaffen. Das stärkt auch das Vertrauen in die Fertigkeiten des gesamten Teams, und Mentalitäten wie: Man müsse die faulen und unfähigen Programmierer kontrollieren und antreiben, damit sie einen Finger rühren, kommen gar nicht erst auf. In Projekten, die regelmäßig gute Qualität abliefern und ihre Termine einhalten, kommt selten der Wunsch auf, alle möglichen Prozessmetriken einzuführen.
Blockchain – eine Einführung
Das Konzept Blockchain ist grundlegender Bestandteil der verschiedenen Kryptobezahlmethoden wie Bitcoin und Ethereum. Was hat es aber mit der Technologie Blockchain auf sich und wozu kann man dieses Konzept noch anwenden? Grundlegend kann man sagen, dass Blockchain wie die Datenstruktur der rückwärtsverketteten Liste aufgebaut ist. Jedes Element der Liste zeigt auf den Vorgänger. Was macht die Blockchain aber nun so besonders?
Blockchain erweitert das Konzept der Liste um verschiedene Rahmenbedingungen. Eine dieser Rahmenbedingungen ist, sicherzustellen, dass kein Element der Liste verändert oder entfernt werden kann. Das lässt sich recht einfach bewerkstelligen. Hierzu verwendet man eine Hashfunktion. Wir codieren über einen Hashalgorithmus den Inhalt eines jeden Elements in der Liste zu einem Hash. Es gibt mittlerweile ein breites Angebot an Hashfunktionen, von denen ein aktueller Standard SHA-512 ist. In nahezu jeder Programmiersprache ist dieser Hashalgorithmus in der Standardbibliothek bereits implementiert und man kann ihn einfach verwenden. Im Konkreten bedeutet es, dass über die gesamten Daten eines Blockes der Hash SHA‑512 gebildet wird. Dieser Hash ist stets eineindeutig und kommt nicht noch einmal vor. Somit dient der Hash als Identifier (ID), um einen Block zu finden. Ein Eintrag in dem Block ist der Verweis auf seine Vorgänger. Dieser Verweis ist der Hashwert des Vorgängers, also seine ID. Bei der Implementierung einer Blockchain ist es essenziell, dass der Hashwert des Vorgängers Bestandteil der Berechnung des Hashwertes des aktuellen Blockes ist. Dieses Detail sorgt dafür, dass die in der Blockchain geänderten Elemente nur sehr aufwendig geändert werden können. Man muss sozusagen für das Element, das man manipulieren möchte, alle nachfolgenden Elemente ebenfalls ändern. Bei der umfangreichen Blockchain mit sehr vielen Blöcken bedeutet so ein Vorhaben einen enormen Rechenaufwand, der nur sehr schwer bis überhaupt nicht zu leisten ist.
Durch diese Verkettung erhalten wir eine lückenlose Transaktionshistorie. Dieser Umstand erklärt auch, weswegen Kryptobezahlmethoden nicht anonym sind. Auch wenn der Aufwand, einen Transaktionsteilnehmer eindeutig zu identifizieren, enorm werden kann. Nutzt dieser Transaktionsteilnehmer zudem noch verschiedene Verschleierungsmöglichkeiten mit unterschiedlichen und nicht durch weitere Transaktionen verknüpften Wallets, steigt der Aufwand exponentiell an.
Natürlich hat der gerade beschriebene Mechanismus noch erhebliche Schwachstellen. Denn Transaktionen, also das Hinzufügen neuer Blöcke, können erst als verifiziert und sicher eingestuft werden, wenn genügend Nachfolger in der Blockchain hinzugekommen sind, die sicherstellen, dass Änderungen wieder schwerer zu bewerkstelligen sind. Für Bitcoin und Co. gilt eine Transaktion als sicher, wenn fünf Nachfolgetransaktionen sind.
Damit es nun nicht nur eine Instanz gibt, die die Transaktionshistorie, also alle Blöcke der Blockchain, aufbewahrt, kommt ein dezentraler Ansatz ins Spiel. Es gibt also keinen zentralen Server, der als Vermittler agiert. Ein solcher zentraler Server könnte durch den Betreiber manipuliert werden. Man hätte so die Möglichkeit, mit genügend Rechenleistung auch sehr umfangreiche Blockchains neu aufzubauen. Im Kontext von Kryptowährungen spricht man hier von einer Reorganisation der Chain. Dies ist auch die Kritik an vielen Kryptowährungen. Außer Bitcoin existiert keine andere dezentrale und unabhängige Kryptowährung. Wenn die Blockchain mit allen ihren enthaltenen Elementen öffentlich gemacht wird und jeder Nutzer eine eigene Instanz dieser Blockchain lokal auf seinem Rechner besitzt und dort Elemente hinzufügen kann, die dann mit allen anderen Instanzen der Blockchain synchronisiert werden, haben wir einen dezentralen Ansatz.
Die Technologie zur dezentralen Kommunikation ohne einen Vermittler nennt sich Peer to Peer (P2P). P2P Netzwerke sind besonders in ihren Entstehungsphasen, also wenn nur wenige Teilnehmer im Netzwerk sind, schwach und angreifbar. Man könnte einfach mit sehr viel Rechenleistung eine große Anzahl von sogenannten Zomi Peers erstellen, die das Verhalten des Netzes beeinflussen. Gerade in Zeiten, in denen das Cloud-Computing mit AWS und der Google Cloud Platform als Anbieter, für vergleichsweise wenig Geld schier endlose Ressourcen bereitstellen kann, ist dies ein nicht zu unterschätzendes Problem. Besonders wenn es einen sehr hohen finanziellen Anreiz für Betrüger gibt, darf man diesen Punkt auf keinen Fall vernachlässigen.
Auch bei P2P gibt es verschiedene Konzepte, die miteinander konkurrieren. Um eine stabile und sichere Blockchain zu implementieren, ist es notwendig, nur auf Lösungen zurückzugreifen, die ohne unterstützende Backbone Server auskommen. Es soll vermieden werden, dass sich eine Master Chain etablieren kann. Daher müssen Fragen geklärt werden, wie sich die einzelnen Peers finden können und mit welchem Protokoll sie ihre Daten synchronisieren. Als Protokoll verstehen wir ein Regelwerk, also ein festes Schema, wie die Interaktion zwischen den Peers geregelt wird. Da bereits dieser Punkt sehr umfangreich ist, verweise ich zum Einstieg in das Thema auf meinen Vortrag 2022.
Eine weitere Eigenschaft von Blockchain‑Blöcken ist, dass sich diese problemlos und mit wenig Mühe auf Gültigkeit hin verifizieren lassen. Hierzu muss lediglich über die gesamten Inhalte eines Blocks der SHA-512 Hash erzeugt werden. Stimmt dieser mit der ID überein, ist der Block gültig. Aber auch zeitrelevante beziehungsweise zeitkritische Transaktionen, wie sie bei Bezahlsystemen relevant sind, lassen sich mit wenig Aufwand erstellen. Dazu werden auch keine komplexen Zeitserver als Vermittler benötigt. Jeder Block wird um einen Zeitstempel erweitert. Dieser Zeitstempel muss allerdings den Ort, an dem er erstellt wird, berücksichtigen, also die Zeitzone mit angeben. Um den Standort der Transaktionsteilnehmer zu verschleiern, können auch alle Uhrzeiten der verschiedenen Zeitzonen auf die aktuelle UTC 0 umgerechnet werden.
Um sicherzustellen, dass die Uhrzeit auch korrekt auf dem System eingestellt ist, kann man einen Zeitserver für die aktuelle Uhrzeit beim Start der Software abfragen und bei Abweichungen einen Hinweis zur Korrektur ausgeben.
Natürlich sind zeitkritische Transaktionen mit einer Reihe von Problemen behaftet. Es muss sichergestellt werden, dass eine Transaktion in einem festgelegten Zeitfenster durchgeführt wurde. Ein Problem, mit dem sich sogenannte Echtzeitsysteme auseinandersetzen müssen. Aber auch das Double Spending Problem muss verhindert werden. Also, dass derselbe Betrag zweimal an unterschiedliche Empfänger gesendet werden kann. Was in einem dezentralisierten Netzwerk die Bestätigung der Transaktion von mehreren Teilnehmern erfordert. Aber auch klassische Race Conditions können ein Problem darstellen. Race Conditions lassen sich durch die Anwendung des Immutable-Entwurfsmusters auf die Block-Elemente beherrschen.
Damit die Blockchain nun nicht durch Spam-Attacken gestört wird, benötigen wir eine Lösung, die das Erstellen eines einzelnen Blocks in der Masse teuer macht. Das erreichen wir, indem wir die Rechenleistung einbeziehen. Hierzu muss der Teilnehmer, der einen Block erstellt, ein Puzzle lösen, das eine ‚gewisse‘ Rechenzeit beansprucht. Wenn ein Spammer das Netzwerk mit vielen Blöcken fluten möchte, steigt seine Rechenleistung exorbitant an und es ist ihm unmöglich, in kurzer Zeit beliebig viele Blöcke zu erzeugen. Dieses kryptografische Puzzle nennt man Nonce, was für „number used only once“ steht. Der Mechanismus Nonce in der Blockchain wird auch oft als Proof of Work (POW) bezeichnet und dient bei Bitcoin zur Verifizierung der Blöcke durch die Miner.
Die Nonce ist eine (pseudo) zufällige Zahl, zu der ein Hash generiert werden muss. Dieser Hash muss dann ‚bestimmte‘ Kriterien erfüllen. Das können zum Beispiel zwei oder drei führende Nullen im Hash sein. Damit man nun keinen beliebigen Hash in den Block einfügt, wird die Zufallszahl, die das Rätsel löst, direkt abgespeichert. Eine bereits genutzte Nounce darf kein weiteres Mal verwendet werden, da sonst das Rätsel umgangen werden kann. Erzeugt man nun aus der Nonce den Hash, muss dieser die Vorgaben z. B. führende Nullen erfüllen, um akzeptiert zu werden.
Da je mehr Blöcke in einer Blockchain enthalten sind, es immer schwieriger wird, eine gültige Nonce zu finden, ist es notwendig, die Regeln für so eine Nonce zyklisch, beispielsweise alle 2048 Blöcke, zu verändern. Das bedeute aber auch, dass die Regeln für eine gültige Nonce ebenfalls den entsprechenden Blöcken zugeordnet werden müssen. Ein solches Regelwerk für die Nonce lässt sich problemlos über eine RegEx formulieren.
Mittlerweile haben wir auch eine beachtliche Menge an Regelwerk für eine Blockchain kennengelernt. Sodass es nun an der Zeit ist, sich ein wenig Gedanken über die Performance zu machen. Würden wir alle einzelnen Blöcke der Blockchain einfach in einer Liste abspeichern, würde uns recht bald der Arbeitsspeicher ausgehen. Jetzt könnte man die Blöcke auch in einer lokalen Datenbank speichern, was auch bei einer Embedded-Lösung wie SQLlite durchaus negative Auswirkungen auf die Geschwindigkeit der Blockchain haben würde. Eine einfache Lösung wäre hier, die Blockchain in gleichlange Teile zu zerlegen, sogenannte Chunks. Ein Chunk hätte sozusagen eine feste Länge von 2048 validen Blöcken und der erste Block eines neuen Chunk zeigt auf den letzten Block des vorhergehenden Chunk. In jedem Chunk kann man auch eine zentrale Regel für die Nonce hinterlegen und mögliche Metadaten wie beispielsweise Min- und Max-Zeitstempel abspeichern.
Wenn wir unseren aktuellen Stand des Blockchain-Regelwerks kurz rekapitulieren, kommen wir aktuell auf drei verschiedene Ebenen. Die größte Ebene ist die Blockchain selbst, welche grundlegende Metainformationen und Konfigurationen enthält. Solche Konfigurationen sind etwa der verwendete Hash Algorithmus. Die zweite Ebene stellen die sogenannten Chunks dar, die eine festgelegte Menge an Block-Elementen enthalten. Wie bereits erwähnt enthalten die Chunks auch Metadaten und Konfigurationen. Das kleinste Element der Blockchain ist der Block selbst, der aus einer ID, den beschriebenen Zusatzinformationen wie Zeitstempel und Nonce und dem Payload besteht. Der Payload ist eine allgemeine Bezeichnung für jedes beliebige Datenobjekt, das durch die Blockchain überprüfbar gemacht werden soll. Für Bitcoin und andere Kryptowährungen ist der Payload die Information, welcher Betrag von Wallet A (Quelle) an Wallet B (Ziel) transferiert wird.
Die Blockchain-Technologie eignet sich aber auch für viele andere Anwendungszenarien. So könnten beispielsweise die Hashwerte von Open-Source-Software Artefakten in einer Blockchain gespeichert werden. Damit könnte man auch Binärdateien aus unsicheren Quellen herunterladen und gegen die entsprechende Blockchain verifizieren. Das gleiche Prinzip wäre auf für die Signaturen von Antivirenprogrammen denkbar. Aber auch im behördlichen Umfeld könnten Anträge und andere Dokumente rechtssicher übermittelt werden. Die Blockchain würde hier als ‚Posteingangsstempel‘ funktionieren. Aber auch Buchhaltung inklusive aller Belege der Warenwirtschaft aus dem Einkauf und der verkauften Artikel und Dienstleistungen sind denkbare Szenarien.
Eine Erweiterung der Blockchain wäre je nach Anwendungsfall die eindeutige Signierung eines Blocks durch den Ersteller. Hierzu käme das klassische PKI Verfahren mit dem öffentlichen und privaten Schlüssel zum Einsatz. Der Unterzeichner speichert in Block seinen öffentlichen Schlüssel, erstellt mittels seines geheimen Schlüssels über den Payload eine Signatur, die als Signatur ebenfalls im Block mitgespeichert wird.
Bisher gibt es zwei frei verfügbare Implementierungen der Blockchain, BitcoinJ und für Ethereum Web3j. Natürlich ist es möglich, mit den gerade beschriebenen Prinzipien auch eine eigene allgemeingültige Blockchain-Implementierung zu erstellen. Hier liegen die Stolperfallen natürlich in den Details, von denen ich in diesem Artikel bereits einige angesprochen habe. Grundsätzlich ist Blockchain aber auch keine Raketentechnologie und für erfahrene Entwickler gut beherrschbar. Wer mit dem Gedanken spielt, sich an einer eigenen Implementierung zu versuchen, hat nun genügend Grundwissen, um sich mit dem notwendigen Detailwissen in den verschiedenen zum Einsatz kommenden Technologien tiefer vertraut zu machen.
PDF-Generierung mit TP-CORE
PDF ist vermutlich das wichtigste interoperable Dokumentenformat zwischen Betriebssystemen und Geräten wie Computer, Smartphone und Tablet. Die wichtigste Eigenschaft für PDF ist die Unveränderlichkeit der Dokumente. Natürlich sind auch hier Grenzen gesetzt und man kann heutzutage problemlos mit entsprechenden Programmen Seiten aus einem PDF Dokument entfernen oder hinzufügen. Dennoch lassen sich die Inhalte der einzelnen Seiten nicht ohne Weiteres verändern. Wo vor Jahren noch kostspielige Spezialsoftware wie beispielsweise Acrobat von Adobe nötig war, um mit PDF umzugehen, sind mittlerweile viele kostenfreie Lösungen auch für den kommerziellen Einsatz verfügbar. So beherrschen die gängigen Office Suiten den Export des Dokumentes als PDF.
Gerade im Geschäftsbereich ist PDF eine hervorragende Wahl, um Rechnungen oder Berichte zu generieren. Hier setzt auch dieser Artikel an. Ich beschreibe, wie einfache PDF Dokumente für die Rechnungslegung etc. genutzt werden können. Komplizierte Layouts, wie sie beispielsweise für Magazine und Zeitschriften in Verwendung kommen, sind nicht Teil dieses Artikels.
Technisch kommt die frei verfügbare Bibliothek openPDF zum Einsatz. Das Konzept ist, aus einem gültigen HTML Code, welcher in einem Template enthalten ist, eine PDF zu generieren. Da wir uns im JAVA Umfeld bewegen, ist die Template Engine der Wahl Velocity. Alle diese Abhängigkeiten nutzt TP-CORE in der Funktionalität PdfRenderer, welche als Fassade implementiert ist. Dies soll die Komplexität der PDF-Generierung in der Funktionalität kapseln und einen Austausch der Bibliothek ermöglichen.
Auch wenn ich nun kein Spezialist der PDF-Generierung bin, habe ich im Laufe der Jahre einige Erfahrungen speziell mit dieser Funktionalität in Bezug auf die Wartbarkeit von Softwareprojekten sammeln können. Dazu gibt es sogar einen Konferenzvortrag. Als ich vor sehr vielen Jahren den Entschluss gefasst hatte, PDF in TP-CORE zu unterstützen, gab es nur die iText-Bibliothek, die zu dieser Zeit mit der Version 5 frei verfügbar war. Ähnlich wie Linus Torvalds mit seinem ursprünglich genutzten Source Control-Management-System, erging es mir. Itext wurde kommerziell und ich brauchte eine neue Lösung. Nun, ich bin nicht Linus, der mal fix GIT aus dem Boden stampft, also habe ich nach einiger Wartezeit openPDF entdeckt. OpenPDF ist ein Fork von iText5. Jetzt musste ich meinen bestehenden Code entsprechend anpassen. Das erforderte einiges an Zeit, war aber dank meiner Kapselung eine überschaubare Aufgabe. In diesem Anpassungsprozess habe ich allerdings Probleme entdeckt, die mir in meiner kleinen Welt bereits das Leben schwer gemacht haben, also habe ich TP-CORE Version 3.0 veröffentlicht, um in der Funktionalität Stabilität zu erreichen. Wer also TP-CORE in einer 2.X Version verwendet, findet dort als PDF Lösung noch iText5. Das soll aber jetzt genug über die Entstehungsgeschichte sein. Kümmern wir uns darum, wie wir aktuell mit TP-CORE 3.1 PDF generieren können. Auch hier gilt: Mein größtes Ziel ist es, eine möglichst hohe Kompatibilität zu erreichen.
Bevor wir beginnen können, müssen wir TP-CORE als Abhängigkeit in unser Java Projekt einbinden. Das Beispiel demonstriert die Verwendung von Maven als Build Werkzeug, kann aber leicht auf Gradle umgestellt werden.
<dependency>
<groupId>io.github.together.modules</groupId>
<artifactId>core</artifactId>
<version>3.1.0</version>
</dependency>
Um etwa eine Rechnung zu generieren, brauchen wir verschiedene Schritte. Zu erst benötigen wir ein HTML Template, das wir mit Velocity erzeugen. Das Template kann natürlich Platzhalter für Namen und Adresse enthalten, wodurch Serienbriefe und Batchverarbeitung möglich sind. Der folgende Code zeigt, wie wir damit umgehen können.
<h1>HTML to PDF Velocity Template</h1>
<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet.</p>
<p>Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.</p>
<h2>Lists</h2>
<ul>
<li><b>bold</b></li>
<li><i>italic</i></li>
<li><u>underline</u></li>
</ul>
<ol>
<li>Item</li>
<li>Item</li>
</ol>
<h2>Table 100%</h2>
<table border="1" style="width: 100%; border: 1px solid black;">
<tr>
<td>Property 1</td>
<td>$prop_01</td>
<td>Lorem ipsum dolor sit amet,</td>
</tr>
<tr>
<td>Property 2</td>
<td>$prop_02</td>
<td>Lorem ipsum dolor sit amet,</td>
</tr>
<tr>
<td>Property 3</td>
<td>$prop_03</td>
<td>Lorem ipsum dolor sit amet,</td>
</tr>
</table>
<img src="path/to/myImage.png" />
<h2>Links</h2>
<p>here we try a simple <a href="https://together-platform.org/tp-core/">link</a></p>template.vm
In dem Template sind drei Properties enthalten: $prop_01, $prop_02 und $prop_03, die wir mit Werten füllen müssen. Das gelingt uns mit einer einfachen HashMap, die wir mit dem TemplateRenderer einfügen, wie das folgende Beispiel zeigt.
Map<String, String> properties = new HashMap<>();
properties.put("prop_01", "value 01");
properties.put("prop_02", "value 02");
properties.put("prop_03", "value 03");
TemplateRenderer templateEngine = new VelocityRenderer();
String directory = Constraints.SYSTEM_USER_HOME_DIR + “/“;
String htmlTemplate = templateEngine
.loadContentByFileResource(directory, "template.vm", properties);Der TemplateRenderer benötigt drei Argumente:
- directory – Der vollständige Pfad vo das Template zu finden ist.
- template – den Namen des Velocity-Templates
- properties – Die HashMap mit den zu ersetzenden Variablen
Das Ergebnis ist ein gültiger HTML Code, aus dem wir nun über den PdfRenderer das PDF generieren können. Eine Besonderheit ist die Konstante SYSTEM_USER_HOME_DIR, welche auf das Nutzerverzeichnis des aktuell angemeldeten Benutzers zeigt und die Unterschiede einzelner Betriebssysteme wie Linux und Windows abfängt.
PdfRenderer pdf = new OpenPdfRenderer();
pdf.setTitle("Title of my own PDF");
pdf.setAuthor("Elmar Dott");
pdf.setSubject("A little description about the PDF document.");
pdf.setKeywords("pdf, html, openPDF");
pdf.renderDocumentFromHtml(directory + "myOwn.pdf", htmlTemplate);Das Listing zum Erstellen der PDF ist überschaubar und recht selbsterklärend. Es ist natürlich möglich, das HTML hardcodiert zu übergeben. Die Nutzung des Templates erlaubt hier eine Trennung von Code und Design, was auch spätere Anpassungen flexibel erlaubt.
Das Standardformat ist A4 mit den Dimensionen size: 21cm 29.7cm; margin: 20mm 20mm; und ist als inline CSS definiert. Über die Methode setFormat(String format); lässt sich dieser Wert individuell festlegen. Der erste Wert steht hierbei für die Breite und der zweite Wert für die Höhe.
Der PDF Renderer hat auch die Möglichkeit, einzelne Seiten aus einem Dokument zu löschen.
PdfRenderer pdf = new OpenPdfRenderer();
PdfDocument original = pdf.loadDocument( new File("document.pdf") );
PdfDocument reduced = pdf.removePage(original, 1, 5);
pdf.writeDocument(reduced, "reduced.pdf");
Wir sehen also, dass bei der Implementierung der PDF Funktionalität sehr viel Wert auf eine einfache Handhabung gelegt wurde. Dennoch gibt es viele Möglichkeiten, individuelle PDF Dokumente zu erstellen. Daher hat die Lösung, über HTML das Layout zu definieren, einen besonderen Reiz. Trotz, dass der PdfRenderer mit einer sehr überschaubaren Funktionalität aufwartet, ist es sehr einfach möglich, durch den Vererbungsmechanismus von Java das Interface und die zugehörige Implementierung durch eigene Lösungen zu erweitern. Diese Möglichkeit besteht auch für alle anderen Implementierungen aus TP-CORE.
TP-CORE ist auch für den kommerziellen Gebrauch frei und hat dank der Apache 2 Lizenz keine Einschränkungen. Der Source Code ist unter https://git.elmar-dott.com zu finden und die Dokumentation inklusive Security und Testcoverage findet sich unter https://together-platform.org/tp-core/.
RTFM – benutzbare Dokumentationen
Ein alter Handwerksmeister pflegte immer zu sagen: Wer schreibt, der bleibt. Seine Intention war vor allem, ein vernünftiges Aufmaß und Wochenberichte seiner Gesellen zu bekommen. Diese Informationen benötigte er, um eine korrekte Rechnung stellen zu können, was für den Erfolg des Unternehmens maßgeblich war. Dieses Bild lässt sich auch gut auf die Softwareentwicklung übertragen. Erst als die in Japan von Yukihiro Matsumoto entwickelte Programmiersprache Ruby eine englischsprachige Dokumentation besaß, begann der weltweite Siegeszug von Ruby.
Wir sehen also, dass Dokumentation einen durchaus hohen Stellenwert für den Erfolg eines Softwareprojektes haben kann. Es beschränkt sich nicht nur auf einen Informationsspeicher im Projekt, wo neue Kollegen notwendige Details erfahren. Natürlich ist für Entwickler Dokumentation ein recht leidiges Thema. Stetig muss diese aktuell gehalten werden und oft fehlen auch Fertigkeiten, um die eigenen Gedanken sortiert und nachvollziehbar für andere auf Papier zu bringen.
Ich selbst kam vor sehr vielen Jahren erstmalig mit dem Thema Dokumentation durch das Lesen des Buches „Softwaretechnik“ von Johannes Siedersleben in Berührung. Dort wurde Ed Yourdon mit der Aussage zitiert, dass vor Methoden wie UML die Dokumentation oft in der Form einer viktorianischen Novelle vorlag. Während meines Berufslebens habe ich auch einige solcher viktorianischen Novellen angetroffen. Das Ärgerliche daran war: Nachdem man sich durch die Textwüste gekämpft hatte – anders als mit Überwindung und Kampf kann man das Gefühl nicht beschreiben –, hatte man die gesuchten Informationen immer noch nicht. Frei nach Goethes Faust: „So steh ich da ich armer Tor und bin so klug als wie zuvor.“
Hier sehen wir bereits einen ersten Kritikpunkt für schlechte Dokumentationen: eine unangemessene Länge der Ausführungen, die wenig Informationen enthalten. Hier müssen wir uns der Tatsache bewusst werden, dass das Schreiben nicht jedem in die Wiege gelegt wurde. Schließlich ist man ja Softwareentwickler und nicht Buchautor geworden. Das bedeutet für das Konzept „erfolgreiche Dokumentation“, dass man möglichst niemanden zu seinem Glück zwingen sollte und sich besser im Team nach Personen umschaut, die für Dokumentation ein Händchen haben. Das soll nun aber nicht bedeuten, dass alle anderen von der Aufgabe Dokumentation freigestellt sind. Ihr Input ist für die Qualität essenziell. Korrekturlesen, auf Fehler hinweisen und Ergänzungen vorschlagen sind durchaus notwendige Punkte, die sich gut auf vielen Schultern verteilen lassen.
Es ist durchaus ratsam, das Team, oder einzelne Teammitglieder gelegentlich rhetorisch zu schulen. Dabei sollte der Fokus auf einer präzisen, kompakten und verständlichen Ausdrucksweise liegen. Dabei geht es auch darum, die eigenen Gedanken so zu sortieren, dass diese auf Papier gebracht werden können und dabei einem roten Faden folgen. Die dadurch verbesserte Kommunikation wirkt sich sehr positiv auf die Entwicklungsprojekte aus.
Eine aktuell gehaltene Dokumentation, die gut zu lesen ist und wichtige Informationen enthält, wird schnell zu einem lebenden Dokument, ganz gleich, welche Formen gewählt wurden. Dies ist auch ein grundlegendes Konzept für erfolgreiches DevOps und agile Vorgehensmodelle. Denn diese Paradigmen setzen auf einen guten Informationsaustausch und adressieren auch das Vermeiden von sogenannten Informationssilos.
Ein Punkt, der mich wirklich triggert, ist die Aussage: Unsere Tests sind die Dokumentation. Nicht alle Stakeholder können programmieren und sind daher auch nicht in der Lage, die Testfälle zu verstehen. Zudem demonstrieren Tests zwar das Verhalten von Funktionen, sie demonstrieren aber nicht per se die richtige Verwendung. Meist fehlen auch Variationen von verwendbaren Lösungen. Damit Testfälle einen dokumentativen Charakter haben, ist es notwendig, spezielle Tests exakt für diesen Zweck zu entwickeln. Dieses Vorgehen hat meiner Ansicht nach zwei gravierende Vorteile. Zum Ersten bleibt die Dokumentation zur Implementierung aktuell, denn bei Änderungen schlägt der Testfall fehl. Ein weiterer positiver Effekt ist, dass der Entwickler über die Verwendung seiner Implementierung bewusst wird und einen ungünstigen Entwurf zeitnah korrigieren kann.
Natürlich gibt es mittlerweile unzählige technische Lösungen, die je nach Sichtweise auf das System für unterschiedliche Personengruppen geeignet sind. Issue- und Bug-Tracking Systeme wie beispielsweise das kommerzielle JIRA oder das freie Redmine bilden ganze Prozesse ab. Sie erlauben es den Testern, erkannte Probleme und Fehler der Software einer Releaseversion zuzuordnen. Projektleiter können mit dem Release Management eine Priorisierung der Korrekturen vornehmen und die Entwickler dokumentieren die verwendete Korrektur. Soweit die Theorie. In der Praxis habe ich in nahezu jedem Projekt erlebt, wie in diesen Systemen die Kommentarfunktion als Chat missbraucht wurde, um den Änderungsstatus zu beschreiben. Als Ergebnis hat man eine Fehlerbeschreibung mit unzähligen nutzlosen Kommentaren und wirkliche weiterführende Informationen fehlen komplett.
Eine weitverbreitete technische Lösung in Entwicklungsprojekten sind auch sogenannte Enterprise Wikis. Sie ergänzen einfache Wikis durch eine Navigation und ermöglichen das Erstellen geschlossener Spaces, auf die nur explizit zugelassene Nutzergruppen feingranulare Berechtigungen wie Lesen oder Schreiben erhalten. Neben der weitverbreiteten kommerziellen Lösung Confluence gibt es auch eine freie Variante namens Blue Spice, die auf dem MediaWiki basiert. Wikis erlauben die kollaborative Arbeit an einem Dokument und die einzelnen Seiten können auch über verschiedene Zusammenstellungen als PDF exportiert werden. Damit die Wikiseiten auch benutzbar bleiben, sollte man Wert auf eine saubere und möglichst einheitliche Formatierung legen. Tabellen sollten mit ihrem Inhalt auf eine A4 Seite passen, ohne dass es zu unerwünschten Umbrüchen kommt. Das verbessert den Lesefluss. Es gibt auch viele Fälle, in denen Aufzählungen der Übersichtshalber Tabellen vorzuziehen sind.
Dies bringt uns auch zu einem weiteren sehr heiklen Thema, den Grafiken. Es ist durchaus korrekt, dass ein Bild oft mehr als tausend Worte sagt. Aber eben nicht immer! Im Umgang mit Grafiken ist es wichtig, sich bewusst zu sein, dass Bilder oft einiges an Zeit für die Erstellung benötigen und oft auch nur mit viel Aufwand angepasst werden können. Daraus ergeben sich einige Konsequenzen, um sich das Leben zu erleichtern. Zum Erstellen von Grafiken wird sich auf ein Standardprogramm (Format) festgelegt. Auf teure Grafikprogramme wie Photoshop und Corel ist zu verzichten. Grafiken, die für Wikiseiten erstellt wurden, sind in ihrem Original, also der änderbaren Datei, an die Wikiseite anzufügen. Es kann auch ein eigenes Repository dafür aufgebaut werden, um so eine Wiederverwendung in anderen Projekten zu ermöglichen.
Wenn ein Bild keinen Mehrwert bedeutet, sollte man darauf besser verzichten. Dazu ein kleines Beispiel. Es ist nicht notwendig, eine Grafik anzufertigen, auf der 10 Strichmännchen abgebildet sind, unter denen dann der Rollenname oder eine Person steht. Hier ist es zielführend, eine einfache Aufzählung anzufertigen, die sich im Übrigen auch leichter ergänzen beziehungsweise anpassen lässt.
Aber auch auf überfrachtete Grafiken sollte man verzichten. Treu nach dem Motto „Viel hilft viel“: Sorgen zu detaillierte Informationen eher für Verwirrung und können zu Missinterpretationen führen. Eine Buchempfehlung ist „Softwarearchitekturen dokumentieren und kommunizieren“ von Stefan Zörner. Er arbeite in diesem Titel optimal heraus, wie wichtig die verschiedenen Sichtweisen auf ein System sind und welche Personengruppen mit einer expliziten Sicht angesprochen werden. Dazu möchte ich auch die Gelegenheit nutzen, um seine 7. Regeln für eine gute Dokumentation wiederzugeben.
- Schreibe aus Sicht des Lesers.
- Vermeide unnötige Wiederholungen.
- Vermeide Mehrdeutigkeiten, wenn nötig Notation erläutern.
- Verwende Standards wie z. B. UML.
- Halte Begründungen (Warum) fest.
- Die Dokumentation ist aktuell zu halten, aber nie zu aktuell.
- Überprüfe die Gebrauchstauglichkeit (Review).
Wer im Projekt damit beauftragt ist, die Dokumentation zu schreiben beziehungsweise deren Fortschritt und Aktualität sicherzustellen hat, sollte sich immer bewusst sein, dass wichtige Informationen enthalten sind, diese auch korrekt und verständlich dargestellt werden. Eine kompakte und übersichtliche Dokumentation lässt sich auch bei fortschreitendem Projekt problemlos anpassen und erweitern. Anpassungen gelingen immer dann am besten, wenn der betroffene Bereich möglichst zusammenhängend ist und möglichst nur einmal vorkommt. Diese Zentralisierung erreicht man durch Referenzen und Verlinkungen, so dass die Änderung im Original sich auf die Referenzen auswirkt.
Natürlich gibt es zum Thema Dokumentation noch viel mehr zu sagen, schließlich ist es Gegenstand verschiedener Bücher, aber das würde den Rahmen dieses Artikels übersteigen. Mir ging es vor allem darum, für das Thema eine Sensibilisierung zu schaffen, denn Paradigmen wie Agilität und DevOps basieren auf einem guten Informationsfluss.
