(Quellcode)-Dokumentation in der Softwareentwicklung

Dokumentation zählt nicht zu den beliebtesten Tätigkeiten von Softwareentwicklern.

Während Quellcode relativ gut dokumentiert wird, findet Projekt-Dokumentation (Wartungshandbücher, Projekthandbücher, Anwenderdokumentationen)  häufig nicht oder nicht ausreichend statt.

Warum ist das so? Warum ist die Quellcode Dokumentation für Entwickler vergleichsweise einfach durchführbar?

Für CosmoCode sind diese Fragen zentral – geht es im sprintDoc Forschungsprojekt doch darum, Dokumentationsprozesse in agile Entwicklungsmethoden zu integrieren.

Ich habe mir die Mühe gemacht und (subjektiv) die Gründe dafür zusammengetragen; inspiriert durch die Teilname an den Analyseworkshops im Forschungsprojekt. Diese Aufstellung stellt einen subjektiven Zwischenstand dar; nach Abschluss der Analysephase werden wir an dieser Stelle aufbereitete Informationen darstellen.

Grund 1: Toolintegration

Dokumentation des Quellcodes wird im Quellcode gemacht. Das bedeutet, dass der Entwickler sich keine Gedanken um das Dokumentationswerkzeug machen muss – er benutzt die selben Instrumente wie bei der Softwareentwicklung.

Grund 2: Vorgegebene Struktur

Die Quellcode Dokumentation erfolgt häufig direkt an der Funktion oder dem Modul. Es gibt keine separate Struktur der Dokumentation; es muss also auch keine separate Struktur geschaffen oder gepflegt werden.

Grund 3: Vorgegebener, existierender Integrationspunkt

Nicht nur die Struktur der Dokumentation ist vorgegeben, sondern auch „das Dokument“, wo dokumentiert wird. Es wird keine Zeit zum Suchen des Dokumentationsortes benötigt; es wird keine Zeit zur Prüfung benötigt, ob ein bestehender Dokumentationsort verwendet werden kann oder einer neuer geschaffen werden muss.

Grund 4: Definierter Use Case & Motivation

Ganz wichtig – der Use case für die Dokumentation ist klar: Quellcode Dokumentation soll in erster Linie (*) dazu dienen, den Quellcode zu verstehen. Dokumentation von Entwickler für Entwickler. Der Nutzen dieser Dokumentation wird jedem Entwickler schlagartig klar, wenn er fremden oder eigenen Code bearbeiten muss. Denn wie sagte Joel Spolsky so schön: „Its harder to read code than to write code“.

(*) Dazu gehört auch die Dokumentation von APIs.

Grund 5: Klare Anforderungen, klarer Kontext, klare Granularität

Wenn „nur“ Funktionen dokumentiert werden, ist die Dokumentation erledigt, wenn das Verhalten der Funktion/des Moduls dokumentiert wird.  Systemübergreifendes Verhalten wird bestenfalls dann dokumentiert, wenn sich Effekte der Funktion woanders zeigen. Dies bedeutet, dass man bestehende Dokumentation hinsichtlich ihrer Korrektheit gut prüfen und anpassen kann. Man muss auch keine anderen Dokumentationsorte sichten und auf Korrektheit prüfen.

Grund 6: Integration in bestehende Prozesse, Publishing

Dokumentation wird zusammen mit dem Quellcode verwaltet; die Versionierung bekommt man frei Haus. Mehr noch: bestehende Deploymentverfahren können dazu genutzt werden, die Publikation über Dok-Generatoren automatisiert anzustoßen.

Was kann man daraus lernen?

  • Dokumentationsaufgaben benötigen (wie Softwareentwicklung auch) klare Anforderungen.
  • Auch Dokumentatinen benötigen eine Approval und eine Definition of done
  • Dokumentationen sollten gemeinsam mit der Software gemanaged werden. Versionen der Software sollten mit Versionen der Dokumentation gekoppelt sein.
  • Dokumentationen sollten eine klare, vorgegebene Struktur haben. Idealerweise sollte sich aus der Softwareanforderung/ bzw dem Quellcode die Stelle in der Dokumentation identifizieren lassen.
  • Dokumentationssysteme sollten mit den Werkzeugen der Entwicklung verknüpft sein. Also mit der IDE, oder dem Aufgaben/Ticket/PM-System

 

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.