# Literate Programming

Hier ist eine **kurze, prägnante und sprachagnostische Anleitung** zu *Literate Programming* **ausschließlich mit Kommentaren in klassischen Quellcode-Dateien**, sodass **kein Build- oder Extraktionsschritt** nötig ist.

## Ziel

Der Code bleibt **direkt ausführbar**, während die **Kommentare die primäre Erzählung** bilden. Menschen lesen die Geschichte, Maschinen ignorieren sie.

## Grundprinzipien

### 1. Kommentare sind das Hauptmedium

* Erkläre **Warum**, **Was** und **Wie** im Kommentar.
* Code ist die **konkrete Umsetzung**, nicht der Text.

```text
# This module computes X.
# The algorithm follows from Y to avoid Z.
```

### 2. Erzählerische Struktur statt technischer Reihenfolge

* Gliedere Kommentare logisch:

  * Motivation
  * Konzepte
  * Entscheidungen
  * Einschränkungen
* Code folgt der Erzählung, nicht umgekehrt.

```text
# Step 1: Prepare input data
code...

# Step 2: Core logic
code...
```

### 3. Kleine, erklärbare Codeblöcke

* Jeder Block beantwortet:
  **„Was tut dieser Abschnitt – und warum?“**
* Maximal wenige Zeilen Code pro Erklärungseinheit.

```text
# Filter invalid entries to avoid later edge cases.
code...
```

### 4. Kommentare beschreiben Absichten, nicht Syntax

❌ Schlecht:

```text
# increment i by 1
```

✅ Gut:

```text
# Iterate sequentially because order is semantically relevant.
```

### 5. Entscheidungen explizit machen

* Halte Alternativen und Gründe fest.
* Besonders wichtig bei „ungewöhnlichem“ Code.

```text
# Use an iterative approach instead of recursion
# because maximum depth is unknown at runtime.
```

### 6. Stabiler Kommentar-Stil

* Einheitliche Marker (z. B. `#`, `//`, `/* */`)
* Optional: leichte Strukturierung

```text
# === Motivation ===
# === Algorithm ===
# === Edge cases ===
```

### 7. Leserorientiert schreiben

* Schreibe für einen **zukünftigen Menschen**, nicht für dich selbst.
* Setze kein implizites Kontextwissen voraus.

## Faustregel

> **Wenn man die Kommentare entfernt, sollte der Code schwer verständlich sein.
> Wenn man den Code entfernt, sollte die Idee klar bleiben.**

## Vorteile dieses Ansatzes

* ✔ Kein Build- oder Extraktionsschritt
* ✔ Funktioniert in jeder Sprache
* ✔ Versionskontroll-freundlich
* ✔ Direkt im Editor lesbar
* ✔ Wartung und Wissenstransfer verbessert