Code-Dokumentation – oder: Wie man Chaos in Klartext verwandelt

Wer schon mal in fremden Code geschaut hat, weiß: Das ist wie in jemand anderes Küche zu gehen und den Salzstreuer zu suchen.
Man findet alles – nur nicht das, was man braucht.
Und genau da kommt Code-Dokumentation ins Spiel. Den Salzstreuer findet man damit aber trotzdem nicht…

Was ist Code-Dokumentation eigentlich?

Code-Dokumentation bedeutet: Den Code so zu erklären, dass ihn auch andere (und du selbst in drei Monaten) verstehen.
Sie ist das Handbuch für alle, die später damit arbeiten – ob Entwickler:innen, Tester:innen oder Technische Redakteur:innen.

Fachbegriff

Quellcode (Source Code)

Das ist der „Rohtext“ einer Software – das, was Entwickler:innen schreiben, bevor das Programm läuft.
Beispiel:

def addiere(a, b):
 return a + b

Es gibt zwei Sorten von Dokumentation:

  • Im Code selbst – also Kommentare, Docstrings, kurze Hinweise

  • Außerhalb des Codes – also Wikis, Handbücher, API-Referenzen, Tutorials

Beides zusammen sorgt dafür, dass Wissen nicht an einzelne Köpfe gebunden bleibt.

Warum Code überhaupt dokumentieren?

Ich erinnere mich an einen Entwickler, der mir mal sagte:

„Wenn der Code gut ist, braucht er keine Doku.“

Ein halbes Jahr später fragte mich derselbe Kunde, wie eigentlich sein eigenes Modul funktioniert.
Tja. 🤷‍♀️
Selbst der beste Code erklärt sich nicht von selbst, besonders, wenn Projekte wachsen, Teams wechseln und Zeit vergeht.

Fachbegriff

API (Application Programming Interface)

Eine Schnittstelle, über die Programme miteinander reden.
Beispiel: Wenn deine App das Wetter anzeigt, nutzt sie wahrscheinlich eine Wetter-API, um die Daten zu holen.

Gute Dokumentation spart also Nerven, Zeit und im besten Fall auch ein paar hitzige Slack-Diskussionen.

Wie Code-Dokumentation aussieht

1. Inline-Kommentare

Das sind die kleinen Notizen direkt im Code. Sie erklären kurz, was oder warum etwas passiert.

# Berechnet den Durchschnitt einer Liste von Zahlen
def durchschnitt(werte):
return sum(werte) / len(werte)

Kleiner Tipp: Kommentiere nicht das Offensichtliche.
Niemand braucht einen Kommentar wie # addiere a und b über a + b.

2. Docstrings – Doku mit System

Viele Sprachen (z. B. Python oder Java) haben sogenannte Docstrings – strukturierte Textblöcke, die automatisch weiterverarbeitet werden können.

def durchschnitt(werte):
 """
Berechnet den Durchschnitt einer Liste von Werten.

:param werte: Liste numerischer Werte
:return: Durchschnitt als float
"""

Diese kleinen Textblöcke sind Gold wert, weil Tools wie Sphinx oder Javadoc daraus automatisch hübsche Dokus bauen.

. Automatische Dokumentationstools

Wenn du Glück hast, läuft die Dokumentation automatisch mit.
Tools wie Doxygen, Sphinx oder JSDoc lesen Code und Kommentare aus und basteln daraus klickbare Doku-Seiten.
Hier können Technische Redakteur:innen richtig glänzen – sie bringen Struktur, Stil und Verständlichkeit rein.

Oder, um es ehrlich zu sagen: Sie machen das Ganze lesbar für Menschen jenseits der Kommandozeile.

Best Practices – aus der Praxis, nicht aus dem Lehrbuch

  1. Schreib wie für deinen Zukunfts-Ich
    Denk dran: In sechs Monaten bist vielleicht du die Person, die keine Ahnung mehr hat, was dein Code tut.

  2. Führe ein Doku-Glossar
    So bleibt die Terminologie konsistent – besonders bei API-Begriffen oder Variablennamen.

  3. Styleguides sind deine Freunde
    Ob Google Developer Style Guide oder interne Richtlinien – Einheit ist König.

  4. Automatisiere, was du kannst
    Baue Dokumentationsprüfungen in CI/CD-Pipelines ein.

  5. Sprich mit den Devs!
    Die besten Dokumentationen entstehen in Zusammenarbeit, nicht im stillen Kämmerlein.

Fachbegriff

CI/CD (Continuous Integration / Continuous Deployment)

Automatisierte Abläufe, die sicherstellen, dass Software nach jeder Änderung getestet, gebaut und veröffentlicht wird – oft inklusive Doku-Updates.

Was Technische Redakteur:innen hier besonders gut können

Technische Redakteur:innen bringen das mit, was in vielen Entwicklerteams fehlt:
Struktur, Klarheit und – tada -Leserorientierung.

Während Entwickler:innen oft im Code denken („Was macht die Funktion?“), denkt die Redaktion im Anwendungsfall („Wer braucht diese Info und wann?“).
Diese Kombination ist mächtig – besonders, wenn es darum geht, Developer Experience (DX) zu verbessern.

Fazit: Code-Doku ist keine Kür, sondern Lebensversicherung

Wer Code schreibt, ohne zu dokumentieren, baut ein Kartenhaus – hübsch, aber wacklig.
Gute Code-Dokumentation sorgt dafür, dass Wissen bleibt, auch wenn Menschen gehen oder Projekte sich ändern.
Und seien wir ehrlich: Wer einmal in gut dokumentierten Code schauen durfte, fühlt sich, als hätte jemand endlich Licht im Keller angemacht.