Entwicklerdokumentation für das Gates Web-Portal

Inhalt

Motivation

Zu den Gates-Software-Projekten existiert derzeit (März 2017) keine nennenswerte Entwicklerdokumentation. Dies betrifft sowohl Inline-Dokumentation in Form von Code-Kommentaren (JavaDoc) als auch übergreifende konzeptionelle Dokumentation (Software-Architektur etc.). Auch die Endpunkte der innerhalb des Webportals bereitgestellten Web-API sind nicht dokumentiert.

Hieraus lassen sich also drei Teilbereiche einer gewünschten Entwicklerdokumentation ableiten:

• Code-Kommentare
• API-Dokumentation
• Konzeptionelle Artikel

Das Ziel der Entwicklerdokumentation ist nicht, zu erklären wie der Code funktioniert. Dies sollte aus sauber geschriebenem Code selbst erkennbar sein (siehe z.B. Clean Code). Das Ziel ist vielmehr zu erklären warum der Code so geschrieben wurde, also genau die Informationen festzuhalten, die beim Verfassen des Codes noch im Kopf sind, aber von einem anderen Entwicklerkollegen oder einem selbst in 6 Monaten nicht mehr so einfach aus dem Quellcode abzuleiten sind. (Siehe dazu auch Write the docs beginner guide)

Da das Schreiben von Dokumentation hart und zeitaufwendig ist und nicht die eigentliche Kernaufgabe des Entwicklers darstellt, sollten folgende Rahmenbedingungen von unserem Dokumentationssystem eingehalten werden:

Dokumentation nah beim Quellcode

Noch schlimmer als keine Dokumentation ist nur veraltete und falsche Dokumentation. Daher sollte jegliche Form von toter Dokumentation wie Word-Dokumente in irgendwelchen Dateiablagen, externe Wikis bei der Entwicklerdokumentation vermieden werden. Kein Entwickler kann auf Dauer die Existenz von solchen, weit vom Code entfernten Dokumenten im Kopf behalten, um diese bei Änderungen zu aktualisieren.

Entwicklerdokumentation sollte also immer möglichst nahe beim Quellcode liegen und zusammen mit diesem unter Versionskontrolle stehen.

Dokumentation in einfachen Textdateien

Es gibt einige Gründe warum Entwicklerdokumentation am besten in der Form von einfachen Textdateien verfasst werden sollte.

1. Entwickler sind es gewohnt mit Textdateien umzugehen. So gibt es auch keinerlei Einstiegshürde und jeder beteiligte Entwickler kann sofort anfangen, Dokumentation zu verfassen.

2. Entwicklern stehen die ausgefeiltesten Versionskontrollmechanismen (Git) zur Verfügung, welche am besten mit einfachen Textdateien funktionieren.

Diesen Vorteilen stehen die eingeschränkte Formatierungsmöglichkeiten entgegen.

Einen sinnvollen und bewährten Kompromiss stellen daher die einfachen Auszeichnungssprachen Markdown und RestructuredText dar.

In diesen Auszeichnungssprachen verfasste Texte können von Online-Diensten wie Bitbucket und Github direkt angezeigt werden. Außerdem können solche Artikel mit Dokumentationstools wie Sphinx oder MkDocs einfach als vollständige HTML-Dokumentationen bereitgestellt werden.

Teildokumentationen

Basierend auf der ausgeführten Motivation folgt hier nun ein Vorschlag zur konkreten Umsetzung einer Entwicklerdokumentation.

1. Kommentare/JavaDoc

Bisher wurden so gut wie gar keine Code-Kommentare gepflegt. Code-Kommentare sind unter Entwicklern ein polarisierendes Thema (siehe auch Clean Code Chapter 4).

Idealerweise sollte der Code für sich sprechen und Code-Kommentare können verständlichen und sauberen Code nicht ersetzen.

Da es beim Entwickeln aber nicht immer vollständig gelingt, diesem Ideal Folge zu leisten, sollten wir uns auf eine sinnvolle und möglichst minimale Vorgehensweise einigen.

Vorschlag minimale Menge an Code-Kommentaren

Dokumentation für jedes Package

Für jedes Java-Package sollte dokumentiert werden, was sich der Entwickler bei dieser Modularisierung gedacht hat, damit auch andere Entwickler die entsprechenden Klassen richtig platzieren können.

Dokumentation von Entitätsklassen

Entitätsklassen, also Klassen die echte Dinge aus der Geschäftswelt abbilden, sollten dokumentiert werden. Hier geht es darum, die Begriffe der Fachdomäne ihren Implementierungen zuzuordnen (oft deutsche Fachbegriffe, aber englische Begriffe im Code). Bei diesen Klassen sollte mindestens die Klasse selbst eine entsprechende fachliche Erklärung bekommen, idealerweise auch alle Eigenschaften der Klasse.

Dokumentation für jeden API-Endpunkt (siehe auch API Dokumentation)

Da ein großer Teil des Webportals schon als clientseitige Javascript-Applikation umgesetzt ist und somit - wie auch die mobile App - die Web-API des Webportals verwendet, sollte diese Ebene als Schnittpunkt zwischen Darstellungslogik und Anwendungslogik fokussiert werden.

Ensprechend soll diese Ebene auch durchgehend mit Kommentaren versehen werden, die die fachliche Funktion des jeweiligen API-Aufrufs kurz erklären.

Mehr dazu unter Web-API-Dokumentation

2. Konzeptionelle Artikel

Hierunter sind frei geschriebene, erklärende Texte zu verstehen, die sich nicht unbedingt auf bestimmte Code-Teile beziehen. Dieser Teil der Dokumentation ist sicher am schwersten zu erstellen. Wenn er gut umgesetzt wird bietet er aber den größten Mehrwert für die Entwickler als auch für die Software-Architektur selbst.

Ausgangspunkt und einer der ersten Artikel sollte ein klassisches Readme sein, wie es als Minimaldokumentation bei den meisten Open-Source-Projekten mittlerweile zu finden ist.

Der Quellcode für diesen Teil der Dokumentation - einfache Textdateien mit Markdown-Syntax - soll zusammen mit dem Code für das Webportal im Git-Repository eingecheckt werden. Dazu wird parallel zum src-Verzeichnis ein Verzeichnis doc angelegt.

Wenn jemand einen neuen Artikel verfassen möchte, kann er diesen zunächst einfach neben dort schon vorhandenen Artikeln als Textfile mit .md-Endung anlegen und einchecken.

Hervorrangende Beispiele für diese Form der Dokumentation sind: Django-Dokumentation, Requests-Dokumentation

Was soll hier dokumentiert werden?

Einen guten Anfang stellen die folgenden Artikel da:

README - Kurzübersicht für neue Entwickler. Welchen Zweck erfüllt die Software? Wie kann ich das Projekt lokal zum laufen bekommen? Was brauche ich, um entwickeln zu können?

FAQ - Seite mit Fragen, die bei der Entwicklung häufiger auftreten.

Darüber hinausgehend sollte das Ziel sein, nach und nach zu allen Schlüsselthemen wie allgemeine Softwarearchitektur, Authentifizierung, Autorisierung, Datenbankschicht, Konzept der API etc. erklärende Artikel auf relativ hohem Abstraktionslevel anzusammeln. Auch hier gilt es vor allem die Gründe für eine bestimmte Umsetzung herauszustellen und möglichst nützliche Hintergrundinformationen zu der Implementierung zu geben. Auf externe Referenzen, z.B. wenn ein Architekturansatz aus einem bestimmten Fachbuch oder einer Open-Source-Software stammt, als sollte über einen Link zur Quelle - nicht über Kopie des Textes - verwiesen werden.

Eine besondere Schwierigkeit bei diesem konkreten Projekt liegt darin, dass Jörn Krueger, der Hauptautor des Web-Portals nichts dokumentiert hat und selbst nicht mehr zur Verfügung steht. Über die genauen Hintergründe einzelner Architekturentscheidungen können wir deshalb oft nur spekulieren. Stattdessen kann es oft sinnvoll sein, zu dokumentieren wenn die vorliegende Implementierung gewisse Besonderheiten aufweist - evtl. auch damit verbundene Probleme oder Fallstricke.

Nach und nach wird sich in einzelnen Bereichen eine neue Architektur ergeben. Diese ist dann unbedingt rechtzeitig zu dokumentieren, damit erstens diese Probleme für zukünftige Entwickler vermieden werden und zweitens die anderen Entwickler dem neuen, hoffentlich besseren Ansatz folgen können, anstatt den bisherigen alten zu kopieren.

Im Zweifel einfach mal anfangen, eigene Artikel zu erstellen. Dadurch dass die Dokumentation mit unter Versionskontrolle steht, lassen sich die Artikel im Nachhinein noch gut redaktionell überarbeiten und selbst wenn dabei großzügig gelöscht werden sollte, geht nichts dauerhaft verloren.

Web-API-Dokumentation

Die Web-API soll in Zukunft als zentraler Dreh- und Angelpunkt des Web-Portals fokussiert werden. Ziel ist es also, diese Schicht so weiter zu entwickeln, dass sie logisch in sich abgeschlossen ist und als sinnvoller Übergabepunkt zwischen Aufgaben der Backend- und Frontendentwicklung zu dienen. Die Dokumentation der Enpunkte sollte automatisch aus den Code-Kommentaren über den API-Endpunkten generiert werden (z.B. mit Swagger).

Dokumentationskonzept muss hier - insbesondere unter Berücksichtigung von automatischer Erstellung der API-Dokumentation - noch erarbeitet werden.