KI-Cluster-Roadmap/00_Globale_Richtlinien/Planung/Namenskonventionen.md

🧩 Namenskonventionen für das KI-Cluster

1. Ziel

Diese Richtlinie legt die einheitlichen Benennungsregeln für alle Dateien, Klassen, Funktionen, Variablen, Logs, Tests und Ressourcen im gesamten KI-Cluster fest.
Durch konsequente Namenskonventionen bleibt das System verständlich, wartbar und maschinenlesbar — insbesondere für automatisch arbeitende Module wie den Builder-Agent.

---

2. Allgemeine Regeln

• Verwende englische Begriffe für Code, Funktionsnamen, Klassen und Module.
  (Nur Dokumentation und Beschreibungen dürfen deutsch sein.)
• Namen sollen beschreibend, aber kurz sein.
• Keine Umlaute, Leerzeichen oder Sonderzeichen in Dateinamen.
• Trennzeichen je nach Kontext:
  • snake_case für Dateien, Funktionen und Variablen
  • PascalCase für Klassen
  • kebab-case (Bindestriche) für Konfigurations- oder YAML-Dateien
  • UPPER_CASE für Konstanten

---

3. Dateibenennungen

Typ	Regel	Beispiel
Python-Dateien	snake_case.py	logic_core.py, api_connector.py
Konfigurationsdateien	kebab-case.yaml oder .json	system-config.yaml
Testdateien	test_<ziel>.py	test_router.py
Markdown-Dokumente	PascalCase.md	KomponentenStandardstruktur.md
Logdateien	<modul>_<datum>.log	router_2025-11-12.log
Diagramme/Bilder	snake_case.png / .svg	system_flowchart.svg

---

4. Klassennamen

• Klassen verwenden PascalCase.
• Präfixe dürfen die Art der Klasse kennzeichnen (optional).
  Beispiele:
  • RouterModule
  • APIModule
  • MemoryManager
  • ConfigLoader
• Abkürzungen vermeiden, außer sie sind allgemein bekannt (API, UI, DB).

Beispiel:

class RouterModule:
    pass

class MemoryManager:
    pass

---

5. Funktions- und Methodennamen

• Verwenden snake_case (Kleinbuchstaben + Unterstriche).
• Funktionsnamen beschreiben Aktionen.
• Wenn eine Funktion boolesche Werte zurückgibt, sollte sie mit is_, has_ oder can_ beginnen.
• Methoden innerhalb von Klassen folgen denselben Regeln.

Beispiele:

def load_config():
    pass

def is_connected():
    return True

def send_message(data):
    pass

---

6. Variablen

• Verwenden snake_case.
• Kurze, aber eindeutige Namen.
• Keine kryptischen Ein-Buchstaben-Variablen außer in Schleifen (i, j, k).
• Bei Konstanten UPPER_CASE.

Beispiele:

connection_status = True
user_name = "admin"
MAX_RETRIES = 5

---

7. Module und Pakete

• Paketnamen immer kleingeschrieben.
• Zusammengesetzte Namen mit Unterstrich trennen.
• Jeder Unterordner mit __init__.py kennzeichnet ein Modulpaket.

Beispielstruktur:

src/
├── api_connector/
│   ├── __init__.py
│   ├── client.py
│   └── handler.py
├── memory_manager/
│   ├── __init__.py
│   ├── database.py
│   └── indexer.py
└── router/
    ├── __init__.py
    └── router_core.py

---

8. Tests

• Jeder Testdateiname beginnt mit test_.
• Testfunktionen folgen der Regel: test_<funktion>
• Tests dürfen dieselben Bezeichner wie das Zielmodul enthalten.

Beispiel:

def test_load_config():
    assert load_config() is not None

---

9. Logging und Ereignisse

• Logdateien folgen dem Schema: <komponente>_<YYYY-MM-DD>.log
• Logmeldungen enthalten Präfixe mit Modul- oder Funktionsname.

Beispiel:

self.logger.info("[RouterModule] Verbindung aufgebaut.")
self.logger.error("[APIModule] Timeout beim Request.")

---

10. Konfigurationen & YAML-Schlüssel

• YAML-Schlüssel sind snake_case, keine Leerzeichen.
• Eindeutige Gruppierung durch logische Sektionen.

Beispiel:

system:
  version: 1.2
  language: de
  mode: production

communication:
  router_endpoint: "http://localhost:5000"
  memory_endpoint: "http://localhost:6000"

---

11. Branch- und Commit-Namen (optional für Git)

Typ	Format	Beispiel
Feature	feature/<beschreibung>	feature/router-logging
Fix	fix/<beschreibung>	fix/memory-leak
Dokumentation	docs/<bereich>	docs/code-style

Commit-Messages folgen dem Schema:

<typ>: <kurze beschreibung>

<optional: längere erklärung>

Beispiel:

feature: API-Modul erweitert

- Neue Endpunkte für Statusabfragen
- Logging-System verbessert

---

12. Zusammenfassung

Diese Namenskonventionen gewährleisten:

• Lesbarkeit und Konsistenz im gesamten Projekt
• Automatische Code-Generierung ohne Konflikte
• Einfaches Wiedererkennen von Modulen und Funktionen
• Einheitliches Verhalten in Tests, Logging und Dokumentation

---

© 2025 – KI-Cluster Homelab Architektur
Autor: [Dein Name oder Alias]