Die Lesbarkeit und Dokumentation von Code sind wichtig, um ihn für andere verständlich zu machen, aber auch für sich selbst. Denn sonst kann es zu einem späteren Zeitpunkt, etwa nach einem Review durch eine Fachzeitschrift, sogar schwierig werden, die eigene Arbeit nachzuvollziehen. Wie bei einem Buch geht es bei der Lesbarkeit von Code darum, wie man diesen schreibt, organisiert und kommentiert. Dazu kommt eine ergänzende Dokumentation über diesen Code. 

Eine gute Lesbarkeit von Code selbst bedeutet beispielsweise:

• Aussagekräftige und einheitliche Namen für Variablen (auch für Funktionen und Klassen) benutzen,
• Code je nach Möglichkeiten der verwendeten Programmiersprache strukturieren  (zum Beispiel in Funktionen und Klassen),
• Code konsistent formatieren (etwa Einrückungen), 
• Kommentare in den Code schreiben, was dieser macht und wozu beispielsweise eine Variable (oder auch eine  Funktion oder Klasse) benutzt wird. Gehen Sie bei der Formulierung davon aus, dass die Lesenden die Grundlagen der Programmiersprache beherrschen. Wenn Ihr Code mit einer wissenschaftlichen Veröffentlichung verknüpft ist, empfiehlt es sich, dass sich beispielsweise die in einer Publikation beschriebene Abfolge von Datenanalyseschritten durch entsprechende Kommentare im Code identifizieren lässt.  

Die Möglichkeiten, Code zu strukturieren, hängen im Wesentlichen von der verwendeten Programmiersprache ab, in der Funktionen und Klassen gängige Begriffe sind. Einen Überblick zu den Möglichkeiten zahlreicher Programmiersprachen finden Sie auf W3 Schools. 

Wie man Code schreibt und organisiert, wird in der Regel für jede Programmiersprache in einem sogenannten Style-Guide festgehalten. Beispiele dafür finden sich bei The Turing Way.

Grundlegende Informationen über den Code (Bezug zu einem Projekt / Fördergeber:in, Autor:innen, Inhaltsbeschreibung zur Funktionalität, Software- und Paket-Abhängigkeiten und so weiter) können Sie auch als Kommentar im Quelltext an zentraler Stelle oder in einer eigenen README-Datei hinterlegen. Wenn Sie ein Code-Repositorium wie GitHub benutzen, gibt es für viele Informationen entsprechende Felder für Metadaten.

Tipp für die Dokumentation: “Ten simple rules for documenting scientific software”