Nachdem wir nun über die Situation und über die Herausforderungen
Probleme gesprochen haben, möchte ich jetzt dazu kommen,
zu sagen, wo können denn Lösungen aussehen?
Was sind die Empfehlungen, die ich Ihnen nennen will, mitgeben will?
Und das sind die Fragen. Damit beschäftigen sich hier die Fragen 3,
4 und 5. Wir machen weiter mit der Folie 69.
Ich habe hier mal verschiedene Sachen zusammengestellt, die ich Ihnen
als Empfehlungen mitgeben möchte. Ja, Empfehlungen für Dinge,
die sie gut in ihren Entwicklungsprozessen in ihren Softwareprojekten umsetzen können,
die geringen Aufwand erfordern, keine Schulung für alle,
keine Überzeugung für alle,
aber ein bisschen
die Situation verbessern
Natürlich ist das nicht der ganz große Wurf,
aber vielleicht kennen sie das Sprichwort, there are snow silver ballett.
Es gibt nicht diese Zauber, diese magische Tauberkugel im Faust spielt er,
wird da diese Silberkugel gegossen, ja, die immer ihr Ziel trifft,
die immer ganz genau die Lösung aller Probleme ist.
Ich denke, das gibt es nicht. Ja,
aber was wir tun können, sind kleine Schritte.
Und ich möchte im Wesentlichen drei Arten von Dokumentationen hier ihnen empfehlen,
auf die erste, gehe ich nicht weiter ein,
weil ich denke, das ist so relativ selbstverständlich,
viele Projekte haben das, dass man versucht,
Überblicksdokumentation zu finden.
Diese Überblicksdokumentation enthält wenig Details. Ich schreibe das jemand dran,
weil dazu gibt es keine separate Folie.
Und weil es so wenig Details hat, ist sie,
gibt es auch wenig Änderungsbedarf. Das ist also ein Überblick.
Meistens heißt es so was Systemarchitektur oder Systemstruktur, Funktionsstruktur oder was auch immer.
Und diese die so einen Überblick über ein System hilft,
dem Einstieg und natürlich auch nur dafür,
weil die Details, wie gesagt, fehlen,
aber Details suchen sich die Leute dann aus dem Quellcode heraus,
beziehungsweise aus anderen Dokumenten, so es die dann gibt.
Also das ist etwas, was ganz viele Projekte mit Erfolg
einsetzen und was schon mal eine deutliche Verbesserung ist gegenüber den Projekten,
wo wir so etwas nicht hat.
Zu den nächsten beiden Fragen werden wir gleich noch auf Folien
etwas sehen, Dokumentation von Entscheidungen und Schnittstellendokumentationen.
Ganz wichtige Informationsquelle für Kommunikationsfragen für das Aufbewahren des Wissens
sind tatsächlich Bezeichner
Entwickler können aus Bezeichnung erst besehen,
finden so viele Informationen aus Bezeichnung heraus,
wenn diese Bezeichnung gut sind, wenn diese Bezeichner Querverweise Referenzen,
nenne ich die jetzt meistens, wenn die das darstellen.
Und Informationen über die Architektur, über Entwurfsentscheidungen sollten Bestandteil des Codes sein.
Wenn die eben Architektur im Code eingebettet sind,
ist es leichter, die mit zu verwenden.
So für die Inhalte, wir wollen Verknüpfungen haben.
Das ist besonders wichtig, damit man dieses Warum versteht.
Ja, das ist auch hier eine von den Wiederholungsfragen.
Welche Informationen Referenzen zwischen welchen Informationen sind am wichtigsten und auch die Trasibility
wird nochmal sich darum drehen. Ja, also hier jedes,
diese Verknüpfungen zum Beispiel, das ist das Erste,
was ich für die Antwort auf diese Frage nennen möchte,
Verknüpfung zur Fachlichkeit, zu Anforderungen.
Das sind hier Geschäftsregeln zum Beispiel. Das ist ein ganz
wichtiger Punkt, weil es wichtig ist für das Verstehen.
Also das ist hier der Punkt. Ja, und das Kernwissen
des Systems zu dokumentieren, das ist natürlich das Entscheidende.
Das Kernwissen sind zum Beispiel bei, geschäftskritischen Systemen häufig
so was wie Geschäftsregeln, die Struktur von Geschäftsobjekten.
Ja, die Datenstruktur können Sie irgendwo finden. Und die
Sequenz können Sie auch irgendwo finden. Aber wir wirklich,
nach welchen logischen Verknüpfungen, was sind die Besonderheiten von solchen Geschäftsregeln?
Das steht nirgendwo. Oder wenn wir Entscheidungen getroffen haben,
zum Beispiel Entwurfsentscheidungen, Entscheidungen über Technologien, Entscheidungen über Entwurfsmuster.
Was ist denn da die Bewertung der verschiedenen Kandidaten gewesen? Ja,
Sie haben dieses Muster, dieses Muster,
dieses Muster als Entwurfsmuster vielleicht als Kandidaten gehabt und dann haben Sie sich für das entschieden,
weil da das Verhältnis zwischen Vor- und Nachteile am besten war.
Das sind Inhalte, die ich Ihnen empfehlen möchte,
also deswegen hier als Empfehlung, die die größte Bedeutung haben. Ja,
und eben das, was wir eben schon sagten,
nicht das Wie-Beschreiben nicht, das sagen, ja,
das funktioniert so und so, das kann man meistens nachlesen,
sondern wir beschreiben das, was wir, warum wir das so entschieden haben.
Ja, und wie kann man das über die Dauer der Entwicklung,
über die Langfristigkeit darstellen, dass du Empfehlungen,
dass man die Abnahme von Kommentaren, die Abnahme von API-Kommenbeschreibungen,
die Abnahme von solchen übergreifenden Dokumentationen,
dass man die mit der Code-Inspektion Code-Reviews verbindet,
also wenn man eine Abnahme macht, dass man die Dokumente dazu auch mit einzieht.
Dass man bei diesen Abnahmen denjenigen, der eigentlich der Nutzer,
der Konsument dieser Beschreibung ist, zum Beispiel andere Entwickler,
zum Beispiel jemand aus dem Operating, der später die Wartung machen wird,
dass sie den mit einbeziehen, oderne Dehnstallationen machen muss,
dass sie den mit einbeziehen, weil er die Sichtweise hat,
welche Informationen brauche ich denn.
Und wenn sie das nicht haben, dann nehmen sie jemanden,
der neu ins Projekt kommt. Da war jemand,
der neu ins Projekt kommt, ist auch ein wichtiger Konsument,
ein Empfänger dieser Beschreibungen,
er möchte daraus lernen und er wird die Fragen stellen,
die die Entscheidend sind
Als Autor fällt einem das selber meistens nicht ein.
Manchmal hält man Sachen für selbstverständlich, weil man sie schon vor
langer Zeit ausgedacht hat, sind aber Schlüsseldinge zum Verstehen.
Ja, und natürlich Werkzeuge, Werkzeuge. Versuchen Sie
Werkzeuge zu verwenden, die die Aktualität, Aktualisierung unterstützen,
die die Übersichtlichkeit unterstützen, die die Navigation unterstützen.
Ja, ich schreibe das mal mit hier dran für Aktualisierung,
für Navigation,
für Prüfung
Diese Werkzeuge helfen uns, sich auf die wichtigen Sachen zu konzentrieren,
statt zu jemandem zu sagen, hier bitte,
schau diese tausendseitigen Schautoster, die das Wiki-Dokument mal durch,
ob es alles korrekt ist.
Das ist eine Aufgabe, die ist nicht zu lösen,
aber wenn wir sagen, hier, dort und, und,
und, dort hat sich was geändert oder dort und dort
scheint es Inkonsistenzen zu geben, ist die Aufgabe viel besser beherrschbar.
So wird erst mal im Überblick, jetzt starten wir mit der Dokumentation von Entscheidungen.
Wie schon gesagt, es kommt vor allen Dingen auf das Warum an.
Es kommt nicht darauf an, wie es gestaltet ist.
Diese Information ist natürlich wichtig, aber diese Information kann ich
auch woanders her gewinnen. Das kann ich auch machen,
indem ich mir den Quiz Melko durchschaue,
indem ich es versuche zu verstehen,
aber ich werde dort nicht die Informationen finden, warum.
Und das ist hier der Punkt, warum besonders wichtig.
Das warum in Anführungszeichen? Ja, also das ist der Punkt,
der hier drinsteht, in der Entscheidung und in den Auswirkungen.
Und der Kontext natürlich, der nochmal sagt, ja,
es geht hier eigentlich um Performance.
Es geht hier um Speicherplatz, es geht um Energieeinsparungen
oder um Robustheit oder um Security
So, und die Empfehlung ist, dass knapp und kurz aufzuschreiben,
das ist dieses Architecture Decision Record auf der nächsten Folie,
kommt gleich noch eine Kurzform davon.
Und die Empfehlung ist, dass mit dem Code gemeinsam abzulegen.
Dann ist es nämlich in der Versionierung drin, dann ist es im Code direkt zu finden.
Ich muss nicht extra irgendwo suchen. Und die Chance,
dass ich es benutzen kann, weil ich es finde.
Und die Chance, dass ich es aktualisiere,
wenn ich etwas daran ändere, ist doch ein bisschen höher.
Das sogenannte Y-Statement ist von meinem Kollegen Olaf Zimmermann und Uwe du ihn zusammen mit anderen entwickelt worden,
ist ein Leichtgewichtiges Architecture Decision Record,
Y im Sinne von warum, ja,
und die haben das so gemacht, eine Art strukturierten Text,
der Kontext, das Problem, was ich löse,
es gab, ich habe mich für etwas entschieden,
es gab noch Alternativen und ich habe dabei auch,
ich sage auch etwas, was sind die Nachteile,
die ich dabei in Kauf nehme.
Für diejenigen, die es nachlesen wollen,
dass Papers nicht allzu lang, ich habe das hier,
ich lege das auch mit im Model ab,
da können Sie
das gerne nochmal nachlesen
Für dieses Wire Statement, wie gesagt, steht für warum,
das Y, ja, und das ist eine Form dieses Architectural Decision Records.
Das ist etwas, was wir hier, die Frage 3 bezieht sich darauf,
wie können Entscheidungen mit geringem Aufwand dokumentiert werden.
Und hier ist der Aufwand wirklich gering. Ja,
wir haben einen, so einen Satz, strukturierten Text,
wir haben die wichtigen Sachen hier alle drin und wenn wir
diesen strukturierten Text wirklich nur in diesem einen Satz irgendwo in die API-Dokumentation mit reinnehmen oder dort,
wo wir die Entscheidung, die Beschreibung dazu haben,
den Zugriff dabei haben, ist es auch leichter zu finden.
Also deswegen, ich habe hier noch ein Beispiel,
das nächste Jahr in The Kontext of the Webshop Service,
Fating the Need to keep you sociation, data consistent to course instances,
we decide for taper that base, session state, pattern.
Also hier geht es um die Entscheidung für einen Entwurfsmuster.
Diese Information allein würde ich vielleicht auch noch finden können,
vielleicht in die Bezeichnung entsprechend gewählt, dass da Database Session,
State Class oder was auch immer steht.
Und hier sehen noch die anderen Alternativen.
Ich habe mich dagegen entschieden, Klein-Session-State oder Server-Session-State
zu verwenden
Es eine wichtige Information war. Und ihr sagt auch noch, warum?
Weil die Cloud-Elastizität und die Data-Konsistenz für uns wichtig waren.
Und wir haben dabei auch etwas akzeptiert als Nachteil.
Manchmal gibt es richtig Nachteile zwischen von den anderen oder auch mal
Nachteil von den Sachen, die wir hier entschieden haben.
Also das als Vorschlag für Entwurfsentscheidungen so im Quelltext zu beschreiben,
so in Dokumenten zu beschreiben. Natürlich sollten sie die auch
ins Viki aufnehmen, wenn es ein Projekt Viki gibt.
Aber in Zeiten von Kram von agiler Entwicklung haben wir,
fokussieren wir uns ja auf Sprints,
auf wenige Dokumente,
auf wenige Sachen für Features
Das nächste Thema, was ich Ihnen vorschlagen möchte,
bezieht sich auf Schnittstellen. Ich denke,
damit haben die meisten von Ihnen schon zu tun gehabt.
Die API-Dokumentation zum Beispiel oder Klassen und Methoden header,
den man mit Javadok oder mit ähnlichen Dokumenten beschreibt.
Diese sind vor allen Dingen gedacht,
für Entwickler andere Elemente, die die Schnittstelle benutzen.
Das heißt, es geht um Informationen über die Schnittstelle, nicht über Interner.
Und typischerweise ist die Schnittstellenbeschreibung völlig klar, was Datentypen bezeichnet betrifft,
was Sichtbarkeit bestrifft. Da steht Public und dann steht,
dass es da ein Rekord von dem und dem gibt und
dass ein Array mit denen denen und eine Liste.
Das gibt es alles. Ja, aber was die Informationen,
die da typischerweise fehlt und die deswegen besonders wichtig ist,
ist die Semantik, die Bedeutung.
Ja, was wird hier gemacht? Welche Aufgabe wird erfüllt
und worauf bezieht die sich? Das ist für das Verständnis
besonders wichtig. Ja, und das ist wiederum das,
was Frage 3 von uns wissen möchte.
Das ist so eine Referenz auf etwas anderes,
nämlich eine Referenz auf Anforderungen und Fachlichkeit
Und wenn ich das,
das kann ich natürlich auch in Bezeichnung ausdrücken, ja,
indem es eben zum Beispiel das Vertragsmodell Vorbedingungen, Nachbedingungen genannt wird,
ja, oder indem man irgendwie in den Winkelsumme,
wenn es dann dieses Beispiel hier ist, als Bezeichner wählt.
Das ist eine gute, also gute Sache, die man da ausdrücken kann.
Dann ganz häufig Sachen, die dem Zusammenspiel mit anderen Elementen dienen.
Es geht ja immer um die Schnittstelle. Also dieses Element,
was wir hier gerade beschreiben und jetzt die anderen,
also Client und Dienstleister,
so heißt das ja bei uns im Vertragsmodell, Ja,
und da sind es vor allen Dingen die Vor- und Nachbedingungen.
Was wird vorausgesetzt? Diese Informationen kann ich ganz schwer aus dem Quellcode nur finden.
Deswegen ist die besonders wichtig. Und dann für Parameter,
natürlich ist ganz klar, welche Datentypen. Die Bezeichnungen sehen sie sowieso,
aber welcher Wertebereich, was sind denn besondere Werte,
was sind besondere Zustände des Systems der Methode, interner Variablen,
irgendwas gibt es Werte, die gerade noch sogar einen Fehler signalisieren.
Ja, besondere Werte. Das sind kritische Sachen und da
könnte man das zum Beispiel mit Javadok gut und darstellen,
dann wird das auch in die API-Dokumentation übernommen und ist dem Quellcode eingebettet.
Auch wir wieder in den Quellcode eingebettet, ist am besten,
weil es sehr wahrscheinlich der Versionierung mit bei der Versionierung mitgenommen wird.
Ebenfalls im Quellcode ist es, sind die Sachen für die Entwickler des gleichen Elementes.
Entweder wie in unserem Comic ganz so anfangen,
weil er es schon vergessen hat oder einfach,
weil es ein Entwickler ist, der später mit dieser Klasse,
mit dieser Methode, mit diesem Modul arbeitet.
Und hier wiederum ganz besonders wichtig, die Entscheidungen,
ich sage das jetzt schon mehrfach, ist, etwas umgesetzt,
das ist meistens relativ klar, aber das Warum, das ist besonders wichtig.
Wir sollten immer daran denken, dass es schwerfällt auf der Code-Ebene,
Abstraktionen zu bilden, Abstraktionen zu erklären.
Man kann das über Bezeichnungen ganz gut machen,
indem man da einen Link zu einem Entwurfsmuster darstellt,
aber das Entwurfsmuster selber im Code darzustellen, ist schwierig,
da brauche ich immer noch separat, die Bezeichnung des Entwurfsmusters.
Und deswegen ist es gut, dass man hier verweist,
woanders, wo etwas steht oder verweist auf Probleme,
die man vermieden hat, Vorteile nennt,
auf Entwurfsmuster verweist,
wo das im Tim Teil ist
Und natürlich, der letzte Punkt ist ein bisschen selbstverständlich.
Ich denke, das haben Sie schon ganz oft gehört.
Man sollte Bezeichner so wählen, dass Sie etwas aussagen,
mit über die Abstraktionen, über die Aufgabe,
über die Bezüge, über die Wertebereiche.
Und dazu darf man durchaus ein paar mehr Zeichen verwenden.
Bezeichner wählen, die etwas aussagen. Das ist ein ganz
wichtiger Punkt. Also wie eine Variable Radius und eine Methode
ist Primzahl. Und das gibt es natürlich im Englischen,
genauso wie im Deutschen.
Das sind alles
ganz wichtige Punkte
Soweit dazu. Wir gucken nochmal zu den Fragen. Ja,
wir hatten hier die Frage vier Referenzen. Was für Verweise,
ich habe diese Verweise, vielleicht schreiben wir hier noch dazu,
dass es eben auch um Referenzen, ach Quatsch,
Referenzen haben wir schon, verweise, weil ich jetzt hier hinschreiben.
Verweise, Bezüge, so etwas heißt das manchmal.
Und letztlich sind auch die Trasibility Links,
die hier in der Frage 5 erfragt werden,
die wir jetzt auf der letzten Folie haben,
sind natürlich auch eine Form von Verweisen.
Wir haben jetzt Verweise auf den letzten paar Folien gehabt,
wo wir die ganz wichtig sind, jedenfalls häufig zum Fachlichen, zur oberübergeordneten Informationen.
Wir gehen gleich noch mal hin zu der Folie 74 hier.
Also verweise zu Abstraktionen. Das ist ganz wichtig,
verweise zu fachlichen Problemen, zu fachlichen Anforderungen sind ganz wichtig.
Diese Abstraktionen, da ist zum Beispiel hier der Algorithmus oder das Entwurfsmuster.
Das sind ganz wichtige Punkte. Eine spezielle Form solcher Verweise,
und das ist der letzte Punkt hier, es sind sogenannte Traceability Links. Trace,
die Spur, die jemand hinterlässt,
das ist die Spur der Entwicklung, sozusagen,
wo bin ich, von welchen Anforderungen bin ich gestartet,
wie bin ich weitergegangen zum Entwurf, wie bin ich weitergegangen zur Implementierung,
wo findet sich das, in welchen Geschäftsprozessen beim Betrieb wieder,
ja, und diese Begriff Trisibility wird verwendet,
um solche Verweise zwischen Artefakten darzustellen.
Der Begriff Artefakt heißt einfach nur von Menschen gemacht,
ist ein Sammelbegriff für alles, was irgendwie entsteht im Prozess,
man könnte auch Dokument dazu sagen,
ein Dokument klingt immer so nach Papier, Artefakt ist das Kunstwort,
Was sagt alles, was gemacht ist?
Ja, also Tracibility, Interrelates, any artefact to any over.
Ja, also das ist, wir verbinden irgendetwas mit irgendetwas.
Das ist Tracibility und wir versuchen, diese Informationen als Verweise, als Referenzen darzustellen.
Und hierzu gibt es auch wieder was zu nachzulesen, eine Arbeit,
an der ich beteiligt war, wo es darum geht,
wie kann ich sowas in Scrum einbetten, in echtgewichtige Prozesse.
Auch dieses Paper finden Sie im Model. Ja,
und Solche Beispiele für solche Verweise, für solche Verknüpfungen zwischen
verschiedenen Sachen, sind zum Beispiel gerade im agilen Umfeld.
Da haben wir für jeden Sprint User-Stories oder in anderen Fällen Objekte und jedenen,
wovon man Use-Case-Beschreibungen, ja,
diese Use-Case-Beschreibung wird dann verknüpft mit zum Beispiel einer API-Beschreibung oder einem Klassenheader oder einem Methodenkopf,
ja, da um zu sagen, worauf bezieht sich denn das?
Das Gleiche, zum Beispiel, wir haben etwas aus dem Marketing,
wo wir sagen, das und das sind die Varianten,
die der Kunde gerne möchte und bei der Konfigurationsanleitung haben wir diese
Bei der Konfiguration stehen diese Varianten zur Verfügung zur Auswahl oder wenn wir ein Template ausfüllen,
können wir sagen, ja, da ist Template,
das bietet hier sind die und die Varianten möglich,
die wir woanders im Marketing haben.
Drittes Beispiel, was ich hier gebracht habe,
man kann logische Bedingungen durch Bezüge, wo sie herkommen,
wo sie definiert sind, besser verständlich machen. Ja,
also zum Beispiel für Testfälle, da haben wir logische Verknüpfungen geprüft,
die guten und die positiven und die negativen Testfälle,
ja, und die werden zum Beispiel aus Vorbedingungen des Vertragsmodells
Die Herausforderung bei diesen Trisibility Links ist eben,
dass sie Annie Art Effects, also verschiedene Typen von Dokumenten miteinander verbinden.
Das heißt, die passen eigentlich nicht in ein Dokument.
Es ist nicht nur Kot, sondern ich habe Kot und Anforderungsbeschreibung.
Es ist nicht nur Entwurf, sondern ich habe
Entwurf- und Anforderungsbeschreibung oder Anforderungsbeschreibung und Test.
Es gibt verschiedene Artefakttypen und da habe ich meistens unterschiedliche Dokumenttypen.
Und deswegen werden häufig solche Trasibility Links in getrennten Dokumenten
in zusätzlichen Dokumenten gespeichert
Zum Beispiel sowas wie eine Art Cross-Referenz, die haben mit Spalten,
haben sie die User-Stories und die Teilen haben sie die Testfälle und da können sie relativ schnell sehen,
wo fehlen denn die Kreuzchen, welcher Use-Case,
welche User-Story ist nicht durch Testfälle abgedeckt oder welcher Testfall deckt besonders viel ab,
man sollte das vielleicht umstrukturieren.
Solche Informationen könnte man zum Beispiel in so einer Cross-Referenztabelle speichern,
die Cross-Referenztabelle könnte, was mit Excel sein,
könnte eine Datenbank sein, die kann ich dann auch auswerten,
die kann ich abarbeiten für Tests und Inspektionen,
aber das ist der Nachteil dieses Externs,
sie ist nicht im Code eingebildet, das Einbetten in den Code,
was ich vorher immer empfohlen habe, Fällt gerade hier schwer.
Aber diese Referenzen, die wir hier haben, ja, interrelated heißt es hier.
Das ist von Besonderem wert, deswegen lohnt es sich hier,
das auch zu machen. Wir haben die letzte Frage,
bezog sich auf diese Trasibility und das ist das gerade,
was ich jetzt hier auch beantwortet habe, ja,
diese Trasibility-Links spielen für das Verständnis eine besondere Rolle,
weil sie die Bezüge herstellen zwischen Sachen,
die ich nicht in einem Dokument finden kann.
Wie Anforderungen und Tests, wie Sachen, die ich fürs Verständnis brauche,
für das Warum brauche, die Begründung und die Ziele.
Somit sind wir hier am Ende. Ich hoffe,
es gelingt Ihnen, Dokumentation gut und mit geringem Aufwand zu machen.
Ich habe jetzt die Frage der Werkzeuge hier nicht einbezogen,
das spielt eine ganz große Rolle, hängt aber ein bisschen davon ab,
welche Werkzeuge sie sowieso erfolgreich im Gebrauch haben in ihren Projekten.
Somit vielen Dank für Ihre Aufmerksamkeit,
viel Erfolg beim Umsetzen und überhaupt viel Erfolg in Ihrer Software-Engineering-Praxis.
Das wünsche ich Ihnen