Burger Menü
Lost in CodePfeil zurück

Lost in Code

Sophie
Sophie
August 2022
Tech Knowhow

Code Dokumentation kann dir dabei helfen, deinen Code übersichtlich zu gestalten. Wie du startest, welche Optionen es gibt und was gute Code Dokumentation ausmacht, erfährst du hier.

Was ist Code Dokumentation?

Die Dokumentation erklärt die Funktionalität des Codes in Form von Kommentaren,  oft auch Docstrings genannt. Ganze Funktionen, deren Parameter und Rückgabewerte können hierbei charakterisiert werden. Code Dokumentation sind Kommentare, die längere Code-Segmente kurz und verständlich zusammenfassen oder näher erläutern.

Beispiel Code-Segmente Python

Aber warum sollte man Code überhaupt dokumentieren?

Wer schon Erfahrungen mit dem Programmieren hat, weiß wie schnell der eigene Code unübersichtlich werden kann oder Code von anderen ohne Dokumentation nur schwer verständlich ist. Eine Dokumentation hilft den Inhalt sinngemäß zu strukturieren. Dadurch wird auch die Zusammenarbeit in einem Projekt erleichtert, da weniger Absprache untereinander nötig ist. Änderungen können leichter eingebaut werden und Fehler fallen eher auf. Eine gelungene Dokumentation hilft somit auch, wertvolle Zeit einzusparen.

Wie dokumentiere ich?

Durch die Kommentare im Code kann man zusätzliche Informationen hinterlegen.

1. Keep it short and simple

Die Kommentare, die zur Dokumentation dienen, sollten kurz gehalten werden und enthalten alle wichtigen Informationen, die man nicht aus dem Code entnehmen kann.

2. Weniger (Text) ist mehr (Info)

Wer mehr Text in der Dokumentation als im Code hat, macht etwas falsch. Ein paar zusätzliche Infos, am besten knapp formuliert, reichen völlig aus.

3. Sinnlose Kommentare

Wer den Code versucht zu verstehen und nur den Namen der Funktion als Beschreibung erhält, kann auch den Code durchlesen. Der Kommentar enthält keine neue Information. Am Besten fügt man in dem Kommentar genau das ein, was nicht ersichtlich ist. Man kann sich vorstellen, dass der Code für jemand anderen erklärt bzw. übersetzt wird.

Falls es einem schwer fällt, kann man sich die klassischen W-Fragen als Stütze nehmen. Zum Beispiel:

- Warum genau dieser Parameter?

- Was für einen Rückgabewert erhalte ich?

- Wofür wird dieser Code benötigt?

Beispiel eines Docstrings einer Funktion mit Beschreibung, Parametern und Rückgabewert

Es gibt auch Programme, die diesen Prozess vereinfachen. Ein weiterer Blogartikel zu diesem Thema folgt in Kürze, stay tuned! :-)