Was ist Code-Dokumentation?

Die Code-Dokumentation dient als Landkarte für diejenigen, die mit einer Codebasis interagieren. Sie hilft ihnen zu verstehen, was die einzelnen Codeabschnitte bewirken, wie sie funktionieren, wie man sie verwendet und wie alle Codeabschnitte zusammenpassen. Die Dokumentation von Code hilft Entwicklungsteams bei der besseren Pflege des Quellcodes und dient gleichzeitig als Leitfaden für andere Stakeholder, die den Code verstehen und damit arbeiten müssen, wie z. B. Cybersicherheitsanalysten , Data Scientists , DevOps-Ingenieure, Produkt- und Projektmanager, QA-Ingenieure und technische Redakteure.

Dokumentation als Code oder „Docs as Code“ behandelt die Dokumentation wie Softwarecode. Dieser Ansatz verwaltet die Dokumentation mit denselben Tools wie der Quellcode, einschließlich Versionskontrollsystemen zur Überprüfung und Nachverfolgung von Änderungen, automatisiertes Testen zur Identifizierung von Formatierungs- und Stilfehlern sowie kontinuierliche Integration/kontinuierliche Bereitstellung (CI/CD) für die Aktualisierung und das Bereitstellen der Dokumentation.

Während die Code-Dokumentation die allgemeinere Praxis der Dokumentation von Code umfasst, ist „Docs as Code“ eine spezifische Strategie und ein eher technischer Ansatz zum Schreiben von Dokumentation.

Die Struktur der Code-Dokumentation hängt davon ab, wer die Zielgruppe ist und wie sie verwendet werden soll. Hier sind einige gängige Arten von Dokumentation:

• Low-Level-Dokumentation
  
  
• High-Level-Dokumentation
  
  
• Interne Dokumentation
• Externe Dokumentation

Low-Level-Dokumentation bezieht sich normalerweise auf Inline-Kommentare im Code. Als eine der grundlegendsten Methoden der Dokumentationserstellung erläutern diese Annotationen bestimmte Codezeilen oder -blöcke.

Dokumentationszeichenfolgen oder Dokumentation sind eine weitere Low-Level-Dokumentationstechnik. Sie erscheinen vor einer Klassen-, Funktions-, Methoden- oder Moduldefinition. Docstrings haben ein strukturiertes Format, das den Zweck, Beispiele für Verwendung, Funktionalität, Parameter und Rückgabewerte deklariert.

Inline-Kommentare eignen sich besser zur Spezifizierung von Logik, wenn diese nicht aus der Untersuchung des Codes selbst abgeleitet werden kann, oder für Code, der auf komplexeren Algorithmen basiert. Unterdessen können Docstrings für die Dokumentation von Programmierschnittstellen (API) extrahiert werden und bieten kontextuelle Unterstützung innerhalb integrierter Entwicklungsumgebungen (IDEs).

Im Gegensatz zu Low-Level-Dokumentationen, die Codeteile als einzelne Entitäten beschreiben, enthält High-Level-Dokumentation Details zu ihrer Rolle im umfassenderen architektonischen Workflow. Diese Art von Softwaredokumentation umfasst Flussdiagramme und Unified Modeling Language (UML)-Diagramme, die die Codearchitektur illustrieren, Designdokumente, die Geschäftslogik und die Übereinstimmung des Codes mit den Produktanforderungen darstellen, sowie Spezifikationen der Struktur von Codebasen oder Code-Repositories.

Diese technische Dokumentation ist für den internen Gebrauch innerhalb eines Unternehmens bestimmt. Beispiele hierfür sind Kodierungskonventionen und Standards sowie Prozessdokumente für die Erstellung von Software durch Teams. Anleitungen zum Einrichten von Entwicklungsumgebungen fallen ebenfalls unter die interne Dokumentation.

Diese anwenderorientierte Dokumentation richtet sich an Entwickler und andere Benutzer außerhalb eines Unternehmens. Die API-Dokumentation beschreibt beispielsweise die verfügbaren Klassen, Funktionen, Methoden und Module der öffentlichen APIs eines Softwareprojekts. Externe Dokumentation kann auch aus Konfigurationsdateien, Integrationsnotizen und einer README-Datei bestehen.

Die README-Datei ist in Markdown verfasst, einer schlanken Auszeichnungssprache zur Formatierung von reinem Text. Sie enthält Informationen über Projektfunktionen, Abhängigkeiten, Installationsanweisungen, Befehle für die Kommandozeile (CLI) und Optionen für Hilfe und Unterstützung. Open-Source-Projekte fügen außerdem Lizenzdetails und Richtlinien für Mitwirkende hinzu, um Pull Requests einzureichen, um Fehlerbehebungen oder Codeänderungen in den Hauptzweig des Code-Repositorys zu integrieren.

Das Schreiben von sauberem und übersichtlichem Code kann eine eigene Form der Dokumentation darstellen. Eine gute Dokumentation bleibt jedoch unerlässlich und bietet folgende Vorteile:

• Verbesserung der Zusammenarbeit

• Verbesserung der Wartbarkeit

• Beschleunigung der Softwareentwicklung

• Rationalisierung des Onboardings

Gut dokumentierter Code fördert bessere Zusammenarbeit und Kommunikation innerhalb der Entwicklungsteams. Mitglieder können Code-Dokumentation als gemeinsame Sprache nutzen, um Code-Reviews durchzuführen, Code-Änderungen zu besprechen und gemeinsam Entscheidungen zu treffen.

Dokumentation erleichtert Code-Refactoring, Wartung und Leistungsoptimierung. Während des Debuggings können Entwickler die Code-Dokumentation als Referenzpunkt nutzen, um Codingfehler zu finden und deren Ursache genau zu bestimmen.

Gute Dokumentation ebnet den Weg für eine schnelle Entwicklung, spart Zeit bei der Lösung der Code-Funktionalität und lenkt den Fokus stattdessen auf die entsprechenden Code-Updates. Sie hilft auch dabei, Änderungen nachzuverfolgen und sicherzustellen, dass die Teams mit einer sich ständig weiterentwickelnden Codebasis Schritt halten können.

Die Code-Dokumentation hilft neuen Teammitgliedern, die Funktionsweise einer Codebasis zu verstehen. Sie können sich schneller mit dem Design und der Struktur des Codes vertraut machen, wodurch sie rasch zum Projekt beitragen können.

Code und Dokumentation gehen Hand in Hand, daher müssen sie sich auch gemeinsam weiterentwickeln. Und einige Richtlinien zum Schreiben von Code gelten ebenso für das Verfassen von Dokumentation. Hier sind Tipps, die helfen können:

• Standards für die Code-Dokumentation festlegen

• Dokumentation in die Codierung integrieren

• Klarheit und Präzision sind entscheidend

• Codierungsentscheidungen dokumentieren 

• Auf dem neuesten Stand halten

Ähnlich wie bei Programmierkonventionen müssen auch bei der Code-Dokumentation Standards eingehalten werden. Diese Standards umfassen konsistente Formatierungen, wie Einzüge, Zeilenumbrüche und Abstand für Low-Level-Dokumentationen. In der Zwischenzeit können Vorlagen und Code-Dokumentationstools bei der Gestaltung und Strukturierung der API-Dokumentation und anderer High-Level- und externer Dokumentation helfen.

Dies kann das Hinzufügen von Docstrings nach Abschluss einer Funktion oder das Einfügen von Inline-Kommentaren bei der Implementierung komplizierter Algorithmen oder Logik beinhalten. Das Schreiben von Dokumentationen während des Programmierens kann Entwicklern helfen, ihren Denkprozess und ihre Entscheidungen zu formulieren und sicherzustellen, dass wichtige Details unterwegs nicht verloren gehen. Es kann am Anfang etwas mehr Zeit in Anspruch nehmen, aber zu einem natürlichen Teil des Codierungsprozesses werden und Debugging, Optimierung und Refactoring beschleunigen.

Eine übermäßige Dokumentation kann die Lesbarkeit des Codes beeinträchtigen. Entwickler müssen der Erstellung von sauberem und übersichtlichem Code Priorität einräumen und anschließend die notwendige Dokumentation hinzufügen, die sich nahtlos in den Code einfügt.

Wenn es um Prägnanz geht, ist es entscheidend, das richtige Maß zu finden. Kurze und einfache Codefragmente benötigen beispielsweise unter Umständen überhaupt keine Dokumentation. Andererseits benötigen komplexere Algorithmen eine Dokumentation, die die zugrunde liegende Logik so erklärt, dass sie auch für Entwickler mit unterschiedlichem Erfahrungsstand verständlich ist.

Dazu gehören Design, Architektur, Logik und algorithmische Entscheidungen. Die Dokumentation dieser Codierungsentscheidungen, sei es durch ein internes High-Level-Dokument oder eine gemeinsame Wissensdatenbank, bietet Kontext für alle Änderungen, die in Zukunft vorgenommen werden sollen.

Entwicklungsteams müssen regelmäßige Reviews und Aktualisierungen ihrer Code-Dokumentation durchführen, um sicherzustellen, dass sie korrekt, vollständig und relevant ist und den aktuellen Stand der Software widerspiegelt. Die Integration von Dokumentation in den Code-Review-Prozess kann bei regelmäßigen Aktualisierungen helfen.

Die meisten IDEs verfügen über Erweiterungen oder Plugins zur Erstellung von Code-Dokumentation, aber auch andere Frameworks und Tools können bei der Automatisierung des Prozesses helfen. Hier sind einige gängige Dokumentationsgeneratoren:

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen unterstützt mehrere Programmiersprachen, wie zum Beispiel C, C++, Java, PHP und Python. Es ermöglicht Markdown-Rendering und kann Dokumentationen in HTML-, PDF- und XML-Formaten erstellen. Doxygen kann über eine Konfigurationsdatei angepasst werden und bietet die Möglichkeit, Diagramme zu generieren, die visuelle Hierarchien und Korrelationen zwischen Klassen und Funktionen darstellen.

GitBook bietet eine Benutzeroberfläche für das Schreiben und Veröffentlichen von Dokumentation als Website, was die Erstellung interner und externer Dokumentation effizienter machen kann. Die Plattform bietet außerdem eine Synchronisierungsfunktion für GitHub- oder GitLab-Repositories.

Das Javadoc-Tool analysiert Dokumentationskommentare innerhalb des Java-Quellcodes, um API-Dokumentation im HTML-Format zu generieren. Es kann Klassen, Konstruktoren, Felder, Schnittstellen und Methoden dokumentieren.

Ähnlich wie Javadoc generiert JSDoc API-Dokumentation für JavaScript-Projekte. Seine Open-Source-Community hat Vorlagen und Tools für die Anpassung der Dokumentation entwickelt.

Sphinx wurde hauptsächlich für Python entwickelt, lässt sich aber auch auf andere Programmiersprachen anwenden. Es unterstützt Markdown und seine eigene Markup-Sprache namens reStructuredText. Sphinx kann Dokumentationen in verschiedenen Ausgabeformaten erstellen und bietet Querverweise, um auf andere Codeelemente zu verweisen.

Dokumentationsgeneratoren sind auf die Anmerkungen beschränkt, denen sie im Quellcode begegnen. Generative KI geht bei der Dokumentation noch einen Schritt weiter, indem sie einen spezifischen Codeabschnitt analysiert und Codekommentare hinzufügt, die dessen Zweck und Funktion beschreiben. Viele große Sprachmodelle (LLMs) für Code verfügen über integrierte Funktionen zur Erstellung von Dokumentation.

Beispielsweise kann IBM® Bob Kommentarzeilen für eine einzelne Methode oder für alle Methoden innerhalb einer Klasse generieren. Weitere ähnliche Tools sind GitHub Copilot, JetBrains AI Assistant, Mintlify und Tabnine.

Wie bei jedem künstlicher Intelligenzsystem müssen Entwickler die Ausgaben von KI-gestützten Code-Dokumentationstools dennoch auf Vollständigkeit und Genauigkeit überprüfen.