lpic-sim/ai/common/coding.md

Coding – allgemeine Verabredungen (alle Sprachen) + Python

Sprachspezifisch gehen vor: bash.md, ansible.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:

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