Björn RundenandClaude Opus 5.5
7f6b8ebe07
Regeln, Standards, Kontextstruktur und Werkzeuge übernommen; 2nd-brain- Inhalte (Stacks, Ansible-Inventar, Architektur, Knowledge) entfernt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# Coding – allgemeine Verabredungen (alle Sprachen) + Python
|
||
|
||
> Sprachspezifisch gehen vor: [bash.md](bash.md), [ansible.md](ansible.md), [docker.md](docker.md).
|
||
|
||
## 1. Für jede Code-Datei
|
||
- **Header** mit Verantwortlichen (`rules/headers.md`) – ohne Ausnahme, auch für Templates und Configs.
|
||
- **Kurz-Doku je Funktion/Klasse:** Zweck, Parameter, Rückgabe – knapp („briefly!“).
|
||
- **Keine Geheimnisse und keine Umgebungsdaten im Code:** Hosts, IPs, Pfade, Domains, Ports → `.env`/Inventar/Konfiguration.
|
||
- **Fehler nie verschlucken:** melden (Log/stderr) und definierten Code zurückgeben. Exit-Codes: 0 ok · 1 Fehler · 2 Aufruffehler.
|
||
- **Logging statt print/echo** für Meldungen; stdout nur für echte Daten.
|
||
- **Dry-Run** (`-n`/`--dry-run`) für alles, was Systeme verändert.
|
||
- **Idempotent**, wo möglich: zweiter Lauf ändert nichts.
|
||
- **Einfach:** kleinste Lösung, die das Ziel erfüllt; keine Vorratsfunktionen, keine unnötigen Abhängigkeiten.
|
||
|
||
## 2. Namen
|
||
| Was | Konvention |
|
||
|---|---|
|
||
| Dateien, Verzeichnisse | Englisch, klein, `_` als Trenner (Ausnahme: Konventionen des Werkzeugs, z. B. `docker-compose.yml`, `README.md`) |
|
||
| Variablen/Funktionen | Englisch, sprechend; Bash `snake_case`, Python PEP 8 |
|
||
| Konstanten/Umgebung | `GROSS_MIT_UNTERSTRICH` |
|
||
| Docker/Compose-Namen | `_` statt `-` (`docker.md`) |
|
||
| Kommentare, Meldungen | Amtssprache |
|
||
|
||
## 3. Konfiguration
|
||
- Reihenfolge überall gleich: **Default < Konfigurationsdatei/.env < Umgebung < Kommandozeile**.
|
||
- `.env` nie im Git, `.env.example` immer mit allen Schlüsseln.
|
||
- Relative Pfade immer zu einer definierten Basis (Script-/Projektverzeichnis), nie zum zufälligen `$PWD`.
|
||
|
||
## 4. Python
|
||
- Python ≥ 3.11, nur Standardbibliothek, wenn vertretbar. Abhängigkeiten in `requirements.txt` (gepinnt) bzw. `pyproject.toml`.
|
||
- Struktur: `main()` + `if __name__ == "__main__": sys.exit(main())`; Optionen mit `argparse` (Standardoptionen analog Bash: `-d/--debug`, `-q/--quiet`, `-n/--dry-run`, `-l/--logfile`).
|
||
- Logging mit `logging` (Konsole + optional Datei, Level aus Umgebung/Option); kein `print` für Meldungen.
|
||
- Header als Modul-Docstring mit denselben Tags:
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
@file sync_dns.py
|
||
@brief Gleicht DNS-Einträge mit dem Inventar ab
|
||
@author <Name aus responsible.md>
|
||
@owner <Name/Rolle aus responsible.md>
|
||
@version 0.1.0 (TT.MM.JJJJ)
|
||
@usage sync_dns.py [-d] [-n] <zone>
|
||
"""
|
||
```
|
||
- Funktionen mit Typannotationen und Kurz-Docstring (eine Zeile Zweck, `Args:`/`Returns:` nur wenn nicht offensichtlich).
|
||
- Pfade mit `pathlib`, Basis `Path(__file__).resolve().parent`.
|
||
- Prüfen: `ruff check`, `ruff format --check` (oder `python -m py_compile`), Tests mit `pytest`, lokal.
|
||
|
||
## 5. Lint & Test (Übersicht)
|
||
| Sprache | Mindestens |
|
||
|---|---|
|
||
| Bash | `bash -n`, `shellcheck -x`, `-h`, `-n`, echter Lauf |
|
||
| Ansible/YAML | `yamllint`, `ansible-lint`, `--syntax-check`, `--check --diff`, Idempotenz |
|
||
| Docker | `docker compose config -q`, Healthcheck `healthy` |
|
||
| Python | `ruff`, `pytest` |
|
||
| Markdown | Links prüfen, `bin/kb_index.sh --check` |
|
||
Was nicht getestet werden konnte, steht ausdrücklich im Ergebnis und in `context.md`.
|
||
|
||
## Änderungsprotokoll
|
||
- 07.10.2026 – angelegt.
|
||
- 23.10.2026 – `$PROJ/context.md` → `context.md` (Einzelprojekt).
|