Initial commit

00_Globale_Richtlinien/Planung/Namenskonventionen.md

@@ -0,0 +1,201 @@
+# 🧩 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:
+```python
+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:
+```python
+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:
+```python
+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:
+```plaintext
+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:
+```python
+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:
+```python
+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:
+```yaml
+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]*