Die Code-Dokumentation

Das Thema Dokumentation ist bei EntwicklerInnen nicht unbedingt beliebt. Dennoch kommt jede EntwicklerIn fast täglich mit dem Thema in Berührung. Zum Beispiel wenn eine EntwicklerIn die Dokumentation einer Dritt-Software liest, die für die eigene Software genutzt werden soll. Oder wenn eine EntwicklerIn direkt im Quellcode Kommentare finden oder ihren eigenen Quellcode selbst kommentiert. Wie viel von so einer Code-Dokumentation im Quellcode nötig und sinnvoll ist, hängt allerdings von verschiedenen Faktoren ab.

• Die Code-Dokumentation
  • Das Für und Wider der Code-Dokumentation
  • Wann man Quellcode dokumentiert
  • Wie man Quellcode dokumentiert
    • Inline-Kommentare
    • DocBlocks
    • Readme-Dateien
  • Tools für die Code-Dokumentation
  • Andere Dokumentationen von und für EntwicklerInnen

Das Für und Wider der Code-Dokumentation

Viele EntwicklerInnen sind der Ansicht, dass ein ideales Software-Projekt auf die Code-Dokumentation weitgehend verzichten kann, wenn es konsequent dem Prinzip des Clean Codes folgt. In diesem Fall wäre der Code so klar strukturiert und so einfach geschrieben, dass sich der Sinn von allein ergibt und Erläuterungen überflüssig sind.

Für Verständlichkeit des Quellcodes sorgt beispielsweise eine sprechende und selbsterklärende Namensgebung von Klassen, Methoden, Funktionen und Variablen. Auch die konsequente Anwendung von Type Hints kann viel zur Klarheit des Codes beitragen, indem sowohl Eingabe- als auch Rückgabewerte definiert werden. Die Nutzung gängiger Design-Patterns und verbreiteter Bibliotheken trägt ebenfalls zur Verständlichkeit bei.

Beispiel: Ein klassischer DocBlock mit Parametern und Rückgabewert.

/**
 * Constructs a new PDO Object and returns it
 *
 * @param string $dbname name of the database to connect to
 * @return PDO connection to the database
 */
private function ConstructPDOObject($dbname) 
{
      ...
      return $pdoConnection;
}

Beispiel: Der gleiche Code bietet mit Typehints dieselbe Verständlichkeit.

private function ConstructPDOObject(string $dbname) : PDO
{
      ...
      return $pdoConnection;
}

In der Praxis begegnet man allerdings nicht immer Clean Code. Und selbst bei einem idealen Code müssen Dokumentationen nicht überflüssig sein. Denn es kommt darauf an, was man wie und für wen dokumentiert:

• Intention: In dem Code kann man die an den Code gestellte Anforderung und die Intentionen des Entwicklers kurz erläutern. Das hilft anderen Entwicklern dabei, die Code-Logik einzuordnen. Auch beim Refactoring kann es sehr wichtig sein, mit der ursprünglichen Intention und Anforderung zu verstehen, ob der Code in dieser Form noch gebraucht wird.
• Logik: Es kann auch sinnvoll sein, die (für Entwickler vielleicht offensichtliche) Logik eines Code-Blocks in einem einfachen Satz wiederzugeben, beispielsweise wenn die Logik Teil einer komplexeren Gesamt-Logik ist. Damit kann bei Bedarf relativ schnell die gesamte Business-Logik nachvollzogen und für die Diskussion mit Nicht-Entwicklern nutzbar gemacht werden. Als Beispiel kann man sich eine Diskussionsgrundlage für das Refactoring eines Notification-Systems zwischen Entwicklern und Produktmanagern vorstellen.

Wann man Quellcode dokumentiert

Quellcode sollte man möglichst sofort während des Entwicklungs-Prozesses dokumentieren, denn dann sind alle Gedanken präsent. Zudem findet man nur in den seltensten Fällen zu einem späteren Zeitpunkt die nötige Muße und Motivation, eher lässte Dokumentationspflichten zu erfüllen.

Wie man Quellcode dokumentiert

Bei der Dokumentation von Quellcode sind Inline-Kommentare und sogenannte DocBlocks üblich. Die genaue Syntax der Kommentare hängt dabei von der Programmiersprache und auch dem verwendeten Dokumentations-Generator ab.

Inline-Kommentare

Inline-Kommentare werden genutzt, um einzelne Code-Zeilen oder Code-Abschnitte zu erläutern. Wie viele Inline-Kommentare man verwendet, hängt von mehreren Faktoren ab. Zum einen sollte man sich fragen, wer den Quellcode liest und welchen Kenntnisstand man erwarten kann. Für Code-Anfänger können Inline-Kommentare sehr hilfreich sein, während erfahrene EntwicklerInnen die Kommentare oft eher überflüssig finden werden. Generell sollte man sich bei jedem Inline-Kommentar fragen, ob eine sprechendere Namensgebung oder ein einfacherer Code nicht mehr zum Verständnis beitragen kann.

DocBlocks

DocBlocks sind die gebräuchlichste Form der Code-Dokumentation. DocBlocks werden einleitend vor Klassen, Methoden und Funktionen geschrieben und folgen einem vorgegebenen Schema. In der Praxis sieht man üblicherweise einen kurzen Titel, einen Beschreibungstext sowie Tags für Eingabewerte (Paramenter) und Rückgabewerte (Return). Zwar sollten die Parameter und Returns schon über Type Hints verständlich sein, allerdings bieten DocBlocks die Möglichkeit, noch auf weitere Details einzugehen.

Ein DocBlock kann beispielsweise so aussehen:

/**
 * Calculates the monthly payment for a loan based on the principal amount, 
 * annual interest rate, and the number of payments.
 *
 * This method implements the fixed-rate monthly payment formula to compute
 * the payment amount for a loan. The calculation accounts for the principal
 * amount, the interest rate per period, and the total number of payments.
 *
 * @param float $principal The total amount of the loan.
 * @param float $annualInterestRate The annual interest rate of the loan as a percentage (e.g., 5.5 for 5.5%).
 * @param int $numberOfPayments The total number of payments to be made.
 * @return float The monthly payment amount. Returns 0 if any input is non-positive.
 */

Die gängigen IDEs unterstützen EntwicklerInnen bei dem Schreiben von DocBlocks und KI-Assistenten wie Copilot können DocBlocks komplett automatisiert verfassen. Damit wird zumindest das Argument des zusätzlichen Zeitaufwands für die Code-Dokumentation entkräftet oder deutlich abgeschwächt. Trotzdem sollte man sich auch bei DocBlocks fragen, in welcher Form sie wirklich sinnvolle Zusatzinformationen zu einem Clean Code mit sprechenden Namen, Type Hints und einer verständlichen Logik bieten.

Readme-Dateien

Eine besondere Form der Dokumentation sind Readme-Dateien, die ebenfalls direkt im Code-Projekt integriert sind und meist eher allgemeine Informationen über die Software, die Installation und die Nutzung bieten. Readme-Dateien sind standardmäßig bei jedem Software-Projekt auf Plattformen wie GitHub oder GitLab integriert. Dort wird aus der zentralen Readme-Dateie die Startseite des Software-Projekts generiert.

Tools für die Code-Dokumentation

Es gibt für die meisten Programmier-Sprachen Tools, mit denen sich automatisch Dokumentationen aus dem Quellcode generieren lassen. Wer sich nicht nur für automatische Dokumentationen sondern auch für redaktionelle Dokumentations-Tools interessiert, findet einige Anregungen in der Tool-Übersicht.

• Sphinx (Python): Ursprünglich für die Dokumentation von Python-Projekten entwickelt, unterstützt Sphinx auch andere Sprachen. Sphinx kann reStructuredText-Dokumentation aus dem Quellcode extrahieren und in mehrere Ausgabeformate umwandeln.
• Pydoc (Python): Ein Tool, das mit Python geliefert wird und HTML-Dokumentation aus den Python-Docstrings generiert.
• Javadoc (Java): Das Standard-Tool von Oracle für Java, das aus den im Quellcode eingebetteten Javadoc-Kommentaren HTML-Dokumentation generiert.
• phpDocumentor (PHP): Ein Tool, das ähnlich wie Javadoc für Java, aus den im PHP-Quellcode vorhandenen DocBlocks umfangreiche Dokumentationen erstellt.
• Doxygen (C++/ C): Das wahrscheinlich bekannteste Tool für die Erstellung von Dokumentation aus Quellcode-Kommentaren für C++, C, Java, Objective-C, Python, und andere Programmiersprachen. Es generiert Dokumentation in verschiedenen Formaten, einschließlich HTML, LaTeX und PDF.
• JSDoc (JavaScript): Ein Analogon zu Javadoc für JavaScript, das es Entwicklern ermöglicht, Dokumentation im HTML-Format aus Kommentaren im Quellcode zu generieren.
• RDoc (Ruby): Das Standard-Dokumentationstool für Ruby, das inline-Dokumentation aus dem Quellcode extrahiert und in verschiedene Formate umwandelt, darunter HTML und RI (Ruby Interactive).

Andere Dokumentationen von und für EntwicklerInnen

Klassische Code-Dokumentationen tendieren häufig dazu, Informationen zu wiederholen, die in einem guten Code ohnehin offensichtlich sind. Ausgesprochen nützlich sind solche Code-Dokumentationen jedoch für die Erzeugung von Code-Referenzen, die häufig Teil der öffentlichen Entwickler-Dokumentation sind. Auch für die API-Dokumentation als spezielle Form der Entwickler-Dokumentation sind Code-Referenzen bzw. die systematische Dokumentation von Endpunkten bedeutsam.

In vielen Fällen können auch interne Software-Dokumentationen sinnvoll sein, die über die eigentliche Code-Dokumentation hinausgeht. Dafür werden oft Wiki-Systeme wie Confluence oder Media-Wiki, aber auch Content Management Systeme genutzt, da an solchen Dokumentationen oft auch Nicht-Entwickler beteiligt sind. In so einer Dokumentation können übergreifende Features oder Logiken beschrieben werden, die sich über mehrere Code-Files und Komponenten verteilen. Es können zum Beispiel zugehörige Tickets mit User-Stories verlinkt, Anforderungen beschrieben oder Schaubilder für Datenbanken oder Systeme integriert werden. Auf dem Enterprise-Level werden häufig ganze System-Architekturen dokumentiert, zum Beispiel mit einer Software wie dem Enterprise Architect.

Im weiteren Sinne gehören auch Commits zum Themenbereich Dokumentation. Commits sind kleine Nachrichten, die bei jeder Code-Änderung für das Versionierungs-Tool Git geschrieben werden. Mit den Commits können EntwicklerInnen andere EntwicklerInnen in einem Satz über die vorgenommenen Änderungen informieren. Aus diesen Commits können jedoch auch sehr gut Changelogs generiert werden, die oft Teil einer Software-Dokumentation sind.

Aufgrund des hohen Zeitaufwandes bleiben solche Dokumentationen meist lückenhaft, sie sollten daher auf zentrale und kritische Bereiche einer Software beschränkt bleiben. In vielen Fällen sind solche Dokumentationen die Basis für eine Diskussionen zwischen EntwicklerInnen, technischen ProjektmanagerInnen und Produkt-EntwicklerInnen.