Wie dokumentiert man den Code einer Datenanalyse für die Abschlussarbeit?

Warum Code-Dokumentation in der Abschlussarbeit unverzichtbar ist

Eine gute Datenanalyse endet nicht mit dem letzten p-Wert. Sie endet erst dann, wenn eine fachkundige Person Ihren Code öffnen, ihn verstehen und Ihre Ergebnisse eigenständig reproduzieren kann. Genau das erwarten viele Betreuer und Prüfungskommissionen von einer wissenschaftlich sauberen Abschlussarbeit.

Das klingt anspruchsvoll – ist in der Praxis aber deutlich erreichbarer als gedacht, wenn man ein paar konsequente Gewohnheiten von Beginn an einführt. Denn Code-Dokumentation ist kein Selbstzweck: Sie schützt Sie selbst davor, drei Wochen nach der Analyse nicht mehr zu wissen, warum ein bestimmter Filter gesetzt oder eine Variable umcodiert wurde.

In der Fachliteratur zu reproduzierbarer Forschung wird betont, dass Dokumentation nicht nur für externe Leser gedacht ist, sondern auch für das zukünftige Ich der forschenden Person – wer Wochen nach der Analyse zurückkehrt, ist in vielerlei Hinsicht genauso auf Dokumentation angewiesen wie eine fremde Person.

Eine klare Projektstruktur als Grundlage

Bevor Sie über Kommentare im Code nachdenken, sollten Sie Ihr Projekt sauber organisieren. Eine nachvollziehbare Ordnerstruktur ist die Basis für alles Weitere.

In der Literatur zu wissenschaftlichem Rechnen hat sich die Trennung nach Dateitypen und Funktion bewährt. Empfohlen wird eine Projektstruktur mit getrennten Verzeichnissen für Rohdaten, bereinigten Daten, Skripte, Ergebnisse und Dokumentation – damit ist auf einen Blick erkennbar, welche Dateien Eingaben sind, welche erzeugte Outputs und welche ausführbaren Analysen.

Eine typische Struktur für eine Abschlussarbeit sieht so aus:

meine-abschlussarbeit/
│
├── README.md               # Projektbeschreibung und Einstiegspunkt
│
├── data/
│   ├── raw/                # Rohdaten – niemals verändern!
│   └── processed/          # Bereinigte, transformierte Daten
│
├── scripts/
│   ├── 01_datenbeinigung.R
│   ├── 02_explorative_analyse.R
│   ├── 03_hauptanalyse.R
│   └── run_all.R           # Zentrales Steuerskript
│
├── results/
│   ├── figures/            # Grafiken und Plots
│   └── tables/             # Ergebnistabellen
│
└── docs/
    └── analyseprotokoll.md # Laufendes Dokumentationsprotokoll

Rohdaten gehören dabei in einen separaten, schreibgeschützten Ordner. Alle Veränderungen an den Daten finden ausschließlich über Skripte statt – niemals durch manuelles Bearbeiten der Originaldatei.

Die README-Datei: Ihr zentrales Orientierungsdokument

Eine README-Datei im Hauptverzeichnis Ihres Projekts ist Pflicht. Sie ist das erste, was jemand liest – und entscheidet darüber, ob Ihr Code verständlich wirkt oder nicht.

Was gehört in eine README?

Für Abschlussarbeiten empfiehlt sich mindestens der folgende Inhalt:

• Projekttitel und Kurzbeschreibung: Worum geht es in der Arbeit, welche Daten wurden analysiert?
• Verwendete Software und Versionen: R 4.3.1, Python 3.11, SPSS 29 – mit konkreten Versionsnummern
• Benötigte Pakete oder Bibliotheken: Welche Packages müssen installiert sein?
• Anleitung zur Ausführung: Wie startet man die Analyse? Welches Skript zuerst?
• Beschreibung der Daten: Woher stammen die Daten, wie wurden sie erhoben, was bedeuten die Variablen?
• Kontaktinformation: Name, Matrikelnummer, Betreuungsperson, Abgabedatum

Konkret empfohlen wird eine README, die neben Projekttitel und Kurzbeschreibung auch Beispiele für zentrale Datenbereinigungs- und Analyseaufgaben sowie alle relevanten Abhängigkeiten enthält. Das mutet nach viel Aufwand an – in der Praxis reichen für eine Bachelorarbeit oft eine halbe bis eine Seite Text.

Format und Ablage

Schreiben Sie die README als einfache Textdatei im Markdown-Format (README.md). Markdown lässt sich in jedem Texteditor öffnen, wird auf Plattformen wie GitHub automatisch gerendert und fügt sich ohne zusätzliche Software nahtlos in Ihr Projekt ein.

Sinnvolle Kommentare im Code

Kommentare sind das direkteste Werkzeug der Code-Dokumentation – aber sie werden oft falsch eingesetzt. Zwei häufige Fehler: entweder gar keine Kommentare, oder mechanische Kommentare, die nur wiederholen, was der Code ohnehin zeigt.

Was sollten Kommentare leisten?

Gute Dokumentation erklärt, warum etwas getan wurde – nicht nur was getan wird. In der Open-Science-Literatur wird empfohlen, Block- und Inline-Kommentare zu nutzen, die begründen, warum eine Entscheidung getroffen wurde – nicht jede einzelne Zeile mechanisch zu erläutern.

Ein schlechtes Kommentierungsbeispiel:

# Mittelwert berechnen
mean(alter)

# NA entfernen
df <- na.omit(df)

Ein gutes Kommentierungsbeispiel:

# Mittleres Alter der Stichprobe (n = 187)
# Grundlage: Stichprobenbeschreibung in Abschnitt 3.2 der Arbeit
mean(df$alter, na.rm = TRUE)

# Fälle mit fehlenden Werten auf der abhängigen Variable (burnout_score)
# werden listenweise ausgeschlossen – Begründung: MAR-Annahme vertretbar
# (Little's MCAR-Test: Chi² = 14.3, p = .11)
df_clean <- df[!is.na(df$burnout_score), ]

Struktur innerhalb eines Skripts

Gliedern Sie jedes Skript mit einem kurzen Header-Kommentar am Anfang. Dieser sollte enthalten:

• Zweck des Skripts (z.B. „Hauptanalyse: Lineare Regression")
• Eingabedaten (z.B. „data/processed/df_clean.csv")
• Ausgabedaten (z.B. „results/tables/regression_output.csv")
• Datum der letzten Bearbeitung und Name

# ============================================================
# Skript:    03_hauptanalyse.R
# Zweck:     Lineare Regressionsanalyse (Hypothese H1–H3)
# Eingabe:   data/processed/df_clean.csv
# Ausgabe:   results/tables/regression_output.csv
#            results/figures/residualplot.png
# Autor:     Maria Musterfrau | Matrikelnr. 12345678
# Betreuung: Prof. Dr. Beispiel | Universität XY
# Datum:     2024-05-15
# ============================================================

Skripte strukturieren und Analysen reproduzierbar machen

Eine vollständige Dokumentation reicht nicht, wenn die Analyse nicht reproduzierbar ist. Reproduzierbarkeit bedeutet: Jemand anderes (oder Sie selbst in drei Monaten) führt Ihre Skripte aus und erhält exakt dieselben Ergebnisse.

Das zentrale Steuerskript

Empfohlen wird, alle Analyseschritte über ein zentrales Skript – häufig run_all.R oder main.py genannt – steuerbar zu machen. So entsteht kein unverbundenes Nebeneinander von Einzelskripten, sondern ein nachvollziehbarer Gesamtworkflow.

# run_all.R – führt die gesamte Analyse in der richtigen Reihenfolge aus

source("scripts/01_datenbereinigung.R")
source("scripts/02_explorative_analyse.R")
source("scripts/03_hauptanalyse.R")

message("Alle Analyseschritte erfolgreich abgeschlossen.")

Versionskontrolle mit Git

Wer seine Analyse mit Git versioniert, hat automatisch ein lückenloses Protokoll aller Änderungen. Jeder Commit ist im Grunde ein dokumentierter Arbeitsschritt. Wichtig dabei: Commit-Messages sollen beschreiben, was geändert wurde und warum – nicht nur „Update" oder „Fix".

Für die statistische Programmierung in Abschlussarbeiten ist Git heute ein Quasi-Standard in den Naturwissenschaften und zunehmend auch in Psychologie und Sozialwissenschaften. Für Einsteiger reicht ein lokales Git-Repository völlig aus – ein GitHub-Account ist optional.

Den Analyseweg dokumentieren: Notizbuch und Protokoll

Code-Kommentare decken den technischen Ablauf ab – aber sie erklären nicht, warum eine Hypothese verworfen, eine Variable ausgeschlossen oder ein Modell nicht weiterverfolgt wurde. Dafür brauchen Sie ein ergänzendes Analyseprotokoll.

Das Analyseprotokoll

Ein einfaches Textdokument (z.B. docs/analyseprotokoll.md) reicht völlig aus. Halten Sie darin fest:

• Datum und Analyseschritt
• Getroffene Entscheidungen und ihre Begründungen
• Verworfene Ansätze – mit kurzer Erklärung, warum sie nicht weiterverfolgt wurden
• Auffälligkeiten in den Daten (Ausreißer, fehlende Werte, unerwartete Verteilungen)
• Bezüge zu Abschnitten in der schriftlichen Arbeit

Besonders wertvoll sind dabei notierte Fehlschläge: Verworfene Wege erklären oft, warum der finale Code so aussieht wie er aussieht – und machen Ihre methodischen Entscheidungen für Prüfende nachvollziehbar.

Jupyter Notebooks und RMarkdown als integrierter Ansatz

Wer mit Python oder R arbeitet, kann Code und Dokumentation direkt kombinieren: Jupyter Notebooks und RMarkdown ermöglichen es, Analysen, Kommentare, Ergebnisse und Interpretationen in einem einzigen Dokument zu führen. Das reduziert den Pflegeaufwand erheblich, weil Code und Erläuterung nicht in getrennten Dateien auseinanderdriften können.

Tools und Formate für die Code-Dokumentation

Die Wahl des richtigen Werkzeugs hängt von der verwendeten Software und den Anforderungen Ihrer Hochschule ab. Die folgende Übersicht gibt Orientierung:

Welche Programmiersprache für Ihre statistische Auswertung am besten geeignet ist, hängt dabei nicht nur von Ihrer Erfahrung ab, sondern auch von Ihrem Fach und der Erwartung Ihrer Hochschule. Wer noch am Anfang steht, findet in unserem Beitrag zum Einstieg in die Statistik-Programmierung einen guten Überblick.

Unabhängig von der Software gilt: Speichern und kommentieren Sie Ihre Syntax konsequent. Warum das gerade für SPSS-Nutzer besonders relevant ist, erläutert unser Beitrag zur Reproduzierbarkeit durch gespeicherte Syntax.

Checkliste: Gut dokumentierter Analysecode

Bevor Sie Ihre Abschlussarbeit einreichen, sollten Sie Ihren Analysecode anhand dieser Kriterien prüfen. Die Empfehlungen orientieren sich an etablierten Standards für reproduzierbare Forschung, wie sie etwa im Bereich Open Science und wissenschaftliches Rechnen verbreitet sind.

Wenn Sie unsicher sind, ob Ihre Dokumentation den Anforderungen Ihrer Hochschule genügt, lohnt sich ein Blick auf die konkreten Vorgaben im Exposé oder in der Prüfungsordnung – oder eine Rücksprache mit Ihrer Betreuungsperson. Was ein Do-File, R-Skript oder eine SPSS-Syntax im Detail voneinander unterscheidet, ist dabei eine nützliche Grundlage.

Gut dokumentierter Code ist letztlich auch ein Zeichen wissenschaftlicher Sorgfalt – und kann im Zweifel den Unterschied zwischen einer überzeugenden und einer lückenhaften Arbeit ausmachen.