# 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