Programmieren ist eine kreative Tätigkeit, mit dem Ziel, eine Anforderung in eine technische Lösung zu übersetzen. Software ist ausführbares Wissen. Die Methode CARDS+ zählt Code darum zur Produktdokumentation. Programmieren ist gleichzeitig dokumentieren, mit Anspruch auf hohe Qualität.

09 Programmieren ist dokumentieren

Lesbarer Code

Ein gutes Buch zu lesen macht Spaß, ein schlechtes legen wir schnell zur Seite. Auch das Lesen von Code sollte daher Spaß machen. Darum halte ich gerne ein Plädoyer für sauberen Code. Ich wende selbst Praktiken wie KISS oder DRY an. Ich versuche, Code nie schlechter zu hinterlassen, als ich ihn vorfinde. Alle wesentlichen Argumente und Ausführungen können auf clean-code-developer.de nachgelesen werden. Aber reichen diese Maßnahmen, um lesbaren Code zu erhalten?

Mein Code

Die Entwickler müssen verstehen, dass es so etwas wie “meinen Code” nicht gibt. Es ist sehr empfehlenswert, in der gemeinsamen Code-Basis einen gemeinsamen Stil zu etablieren. Das fängt mit einer einheitlicher Konfiguration des Code-Formatter an. Wir folgen den Regeln für die Bezeichnung von Namensräumen, Strukturen und Klassen. Im Zusammenhang mit CARDS+ bedeutet das die Verwendung der Namen aus dem Wiki.

Internationale Firmen unterhalten Niederlassungen auf vielen Standorten rund um den Erdball. Nehmen wir an, dass ein Unternehmen Standorte so verteilt, dass drei Entwickler-Teams mit ihren acht Stunden zeitversetzt rund um die Uhr arbeiten. Ein Team über nimmt zu Beginn der Schicht die Code-Basis im Repository. Voraussetzung ist, dass alle Tests grün sind. Im Laufe der Schicht ändern die Entwickler den Code, fixen Fehler, realisieren eine Anforderung. Dieses Vorgehen legt hohe Ansprüche an die Qualität des Codes. Es ist keine Zeit für eine langwierige Übergabe des Codes. Der Code muss für sich sprechen. Selbst Kommentare können problematisch sein: unterschiedliche Sprache, selbst bei englischer Sprache gibt es kulturelle Unterschiede, die das Verständnis des Kommentars erschweren. Besonders spannend ist es, wenn die drei Teams rund um die Uhr im selben Code arbeiten. Innerhalb eines Tages können bis zu zwei andere Entwickler den Code verändern. Code muss daher so geschrieben werden, dass er schnell und sicher verstanden wird. Es muss einfach sauberer Code sein.

Kein Kommentar

Es ist verdammt schwer, Kommentare im Code wirklich aktuell zu halten. Selbst bei größter Disziplin schleichen sich mit der Zeit immer mehr kleine Fehler ein. Am Ende bleibt dem Entwickler nichts anderes übrig, als doch den Code zu lesen. Da drängt sich doch die Frage auf: Wofür brauchen wir Kommentare im Code?

Kommentare sind immer dort notwendig, wo der offensichtlich einfache Weg bei der Umsetzung nicht eingeschlagen wurde. Das kann ein Workaround für einen Bug in einem Framework sein. Oder es ist eine Optimierung des Codes. Alle diese Fälle zeichnen sich dadurch aus, dass wir am Code den Grund für die unerwartete Umsetzung nicht erkennen können.

Hat ein Entwickler das Bedürfnis, einen wichtigen Hinweis als Kommentar im Code zu schreiben, dann sollte er kurz innehalten und sich fragen, ob er dieses Wissen nicht teilen möchte. Eine sehr einfache aber wirkungsvolle Möglichkeit bietet hier das Wiki.

ktip Entwickler können einen Case oder alle Bausteine der Architekturdefinition, die zu einer User-Story im Sprint-Backlog gehören, direkt ändern oder kommentieren. Während des Sprints “gehören” solche Seiten dem cross-funktionalen Team.

Produktwissen

Aber was ist mit Hinweisen zur Logik, zu fachlichen Zusammenhängen? Hier muss es unser klares Ziel sein, dieses wertvolle Wissen im Wiki in der Beschreibung der Lösung im zugeordneten Case zu sichern. Die einfache Regel ist: Was nicht im Code “gelesen” werden kann (“Wie”), gehört ins Wiki (“Wer”, “Wann” und “Warum”).

Es ist wohl richtig, dass die einzige sichere Quelle für detaillierte Informationen der Code ist. Aber es ist schwer, am Code größere Zusammenhänge zu erkennen.  Im Zeitalter der Microservices wird die Sache noch etwas schwieriger. Jedes Microservice ist ein kleiner, in sich abgeschlossener Monolith. Trotzdem benutzen verschiedene Microservices gleiche Daten oder in nachrichten-orientierten Systemen gleiche Nachrichten. Das Wissen über die Informationsobjekte und Nachrichten ist sehr wichtig.

Hier kommt die Methode CARDS+ und das Wiki ins Spiel. Im Wiki definieren wir das Microservice (Baustein Service), alle Informationsobjekte (Baustein Entity) und Nachrichten (Baustein Event). Im Wiki geben wir die Namen vor und beschreiben die Datenstruktur (Syntax) und die fachliche Bedeutung (Semantik). Im Code verwenden wir diesen Namen aus dem Wiki für die konkrete Umsetzung des Microservices. Allein durch den Namen der Klasse stellen wir den Bezug zur Beschreibung im Wiki her. Wir können direkt aus der Beschreibung in den Code wechseln.