docs: Coding Standards Fundament — Regelwerk + Implementierungsplan

2026-06-21 21:36:17 +02:00
parent 20a7f5987a
commit b1a74b7d02
2 changed files with 767 additions and 0 deletions
@@ -0,0 +1,80 @@
+# BSN Coding Standards — Fundament-Plan
+
+> **Für Hermes:** Direkt umsetzen, keine Subagents nötig — kompaktes Setup.
+
+**Ziel:** Verbindliche Coding-Standards für das BSN-Community-Projekt, automatisch durchgesetzt durch Tooling.
+
+**Architektur:** Drei-Schichten-Modell:
+1. **Regelwerk** (`CODING_STANDARDS.md`) — Deutsche Dokumentation, menschenlesbar
+2. **Konfiguration** (`pyproject.toml`) — Ruff (Linter+Formatter), mypy, pytest
+3. **Durchsetzung** (`.pre-commit-config.yaml`) — Automatische Prüfung vor jedem Commit
+
+**Tech Stack:** Ruff 0.11+, mypy 1.15+, pytest 8+, pre-commit 4+
+
+---
+
+## Recherche-Ergebnisse (Stand Juni 2026)
+
+### Konsens der Python-Community
+- **Ruff** hat Black + isort + Flake8 + pyupgrade + Bandit nahezu vollständig abgelöst
+- **mypy** bleibt der Standard für statische Typ-Prüfung
+- **pyproject.toml** ist der zentrale Konfigurationspunkt (PEP 621)
+- **pre-commit** ist der De-facto-Standard für Git-Hooks
+- Line-Length: 88 (Black-Default) oder 100 (moderner Konsens für Web-Apps)
+
+### Für Flask-Webprojekte spezifisch
+- Routes schlank halten (nur Request-Handling, keine Business-Logik)
+- `@app.route()` immer mit expliziten `methods=[...]`
+- Niemals `request.args` für POST-Daten verwenden
+- Immer `send_file()` mit korrektem mimetype
+- Secrets nie im Code — immer über Environment Variables
+
+---
+
+## Aufgaben
+
+### Task 1: CODING_STANDARDS.md schreiben
+**Datei:** `CODING_STANDARDS.md` (Projekt-Root)
+
+Deutsches Regelwerk mit folgenden Abschnitten:
+1. Allgemeine Prinzipien (Lesbarkeit, Konsistenz, Zen of Python)
+2. Code-Stil (PEP 8, Zeilenlänge 100, Quotes, Imports)
+3. Typ-Annotationen (immer, strict, `Optional` statt `| None` für Python <3.10)
+4. Namenskonventionen (snake_case, PascalCase, UPPER_CASE)
+5. Kommentare & Docstrings (Deutsch, Google-Style)
+6. Projektstruktur (keine God-Files, max 500 Zeilen/Modul)
+7. Sicherheit (keine Secrets, Input-Validierung, SQL-Injection)
+8. Testing (pytest, 80% Coverage, TDD)
+9. Flask-spezifische Regeln
+10. Git-Commit-Regeln (Conventional Commits)
+
+### Task 2: pyproject.toml erstellen
+**Datei:** `pyproject.toml` (Projekt-Root)
+
+```toml
+[build-system]
+[tool.ruff] — line-length=100, target-version=py313
+[tool.ruff.lint] — Alle kritischen Rules aktiv
+[tool.ruff.format] — quote-style="double"
+[tool.mypy] — strict=true
+[tool.pytest.ini_options] — testpaths, coverage
+[tool.bandit] — Sicherheits-Scans
+```
+
+### Task 3: .pre-commit-config.yaml erstellen
+**Datei:** `.pre-commit-config.yaml` (Projekt-Root)
+
+Hooks: ruff (lint+format), mypy, Bandit, check-added-large-files, check-merge-conflict, trailing-whitespace
+
+### Task 4: Committen
+```bash
+git add CODING_STANDARDS.md pyproject.toml .pre-commit-config.yaml
+git commit -m "feat: coding standards fundament — Ruff + mypy + pre-commit"
+```
+
+---
+
+## Verifikation
+- `ruff check .` findet keine unerwünschten Issues
+- `mypy .` läuft ohne Fehler (auf neuem Code)
+- `pre-commit run --all-files` läuft durch