# 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).