dbf40c30d8
Add comprehensive documentation for literate programming approach: - Phase 1 guidelines focusing on why/what without implementation - General literate programming principles for code documentation - Project notes explaining wrapper script concept and strategy Decision: Follow literate programming to make the wrapper maintainable and educational. Comments tell the story, code implements it. This foundation enables better collaboration and knowledge transfer. The notes.md establishes the core concept: a reproducible wrapper around the Void installer that automates error-prone LUKS encryption setup while keeping user control over system configuration choices.
2.3 KiB
2.3 KiB
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.
# 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.
# 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.
# Filter invalid entries to avoid later edge cases.
code...
4. Kommentare beschreiben Absichten, nicht Syntax
❌ Schlecht:
# increment i by 1
✅ Gut:
# Iterate sequentially because order is semantically relevant.
5. Entscheidungen explizit machen
- Halte Alternativen und Gründe fest.
- Besonders wichtig bei „ungewöhnlichem“ Code.
# 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
# === 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