In wem der Begriff “Code Dokumentation” keine pure Freude auslöst, ist bei diesem Blogartikel auf jeden Fall richtig. Worum es hier aber eigentlich geht, wird in unserem vorherigen Blog-Beitrag beschrieben.

‍

Was sind Dokumentations-Tools?

‍

In einem Satz kann man sagen, dass die Code Dokumentation die Funktionalität eines Codes in Form von Kommentaren erklärt.

‍

Um diesen Prozess zu vereinfachen, wurden Software-Dokumentations-Tools ins Leben gerufen. Diese helfen, das Schreiben, Teilen und Bearbeiten von Dokumentationen schnell und einfach zu gestalten.

Wie wird das durch die Tools ermöglicht?

‍

Schreiben:

Es existieren bestimmte Tools, die den Quellcode nach Klassenhierarchien und Funktionen scannen. Sogenannte Dokumentations-Generatoren. Diese extrahieren Informationen aus Docblocks und Docstrings.

Teilen:

Viele Dokumentations-Tools haben die Möglichkeit, Dokumente nach Fertigstellung zu veröffentlichen und Dokumente an interne Teams oder externe Benutzer zu verteilen.

Bearbeiten:

Einige Dokumentations-Tools bieten Versionskontrollsysteme, damit Teams im Laufe der Zeit vorgenommene Änderungen nachverfolgen können.

‍

Beliebte Dokumentation-Tools

‍

Es gibt eine große Auswahl an Tools, die zur Verfügung stehen.

Hier habe ich drei beliebte und gängige Tools mit deren jeweiligen In- und Output-Formaten für die Code Dokumentation aufgelistet.

‍

‍

Input bezeichnet hierbei die Programmiersprache, die benötigt wird, damit das jeweilige Tool den programmierten Code auslesen und zu einer Datei zusammenstellen kann.

‍

Diese Datei nennt sich in der Tabelle Output und bezeichnet die vom Tool erzeugte Datei.

‍

Je nach Tool kann der Output variieren. Man kann das Format in den meisten Fällen wählen. Oft handelt es sich um eine HTML-Datei, die auch am häufigsten benötigt wird.

‍

Doxygen Beispiel

‍

Hier siehst du ein Doxygen Beispiel, in dem der Input an Kommentaren in Python verfasst wurde. Diese sind mit # eingeleitet. Die doppelten Hashtags werden dabei dem einmaligen Hashtag untergeordnet.

‍

(Vergleichbar mit den Überschriften in HTML H1 wäre hier # und H2 ##.)

‍

‍

Hier siehst du nun das Ergebnis. Eine geordnete Beschreibung, die leicht zu verstehen ist.

‍

‍

Sphinx Beispiel

‍

‍

In diesem Beispiel habe ich einen Code erstellt, der ein einfaches “Schere, Stein, Papier"-Spiel simuliert. Geschrieben in Python.

‍

Allein durch ein paar Eingaben in das Terminal (und mithilfe von Homebrew) konnte ich Sphinx installieren und mir eine HTML-Datei beziehungsweise Website ausgeben lassen.

‍

Die HTML-Datei kann beliebig angepasst und nach Bedarf erweitert werden, hierfür steht einem eine reStructuredText Datei zur Verfügung.

Das habe ich hier auch gemacht:

‍

‍

Die nun fertig generierte Dokumentations-Website sieht dann wie folgt aus:

‍

‍

Die Search Page oder auch die Quick Search sind ziemlich hilfreich, wenn man sich gerade erst mit dem Code vertraut macht. Damit hat man die Möglichkeit so manchen Modulen oder auch Variablen auf die Spur zu kommen. Denn die Dokumentation kann nach genau der Funktion gefiltert werden, die eventuell einen Bugfix benötigt.

‍

Außerdem kann oft eine Beschreibung hinzugefügt werden. Diese kann dann idealerweise von allen beteiligten Personen eines Projekts (auch ohne Verständnis zur jeweiligen Programmiersprache) gelesen und verstanden werden.

‍

Die sogenannten Python Domain / Directives kann man auf der Sphinx-Homepage unter reStructuredText nachschlagen.

‍

Biz Factory Favorites

‍

Im Biz Factory Kosmos haben wir einige Tools, die genutzt werden. Da so viele verschiedene existieren und jedes Tool besondere Eigenschaften hat, eignen sich manche besser für bestimmte Aufgaben als andere.

‍

Wir nutzen zum Beispiel GitHub Copilot um sinnvolle Beschreibungen für Docstrings zu erstellen.

‍

Für API (Programmierschnittstellen) Dokumentationen halten wir hingegen Swagger als sinnvollste Lösung.

‍

Sphinx auf der anderen Seite, hat die tolle Eigenschaft, dass eine komplette Dokumentations-Website aus den Kommentaren angefertigt werden kann.

‍

Es gibt noch einige andere Tools, die wir zur Code Dokumentation verwenden, ich werde jedoch nicht alle aufzählen, da sie sich auch ändern und jeder von uns eigene Präferenzen hat.

‍

Ich hoffe, dieser kleine Einblick konnte dir eine grobe Idee über die endlosen Tools, die dir für die Dokumentation von Code zur Verfügung stehen geben.

‍

Also: Happy code documentation!