Initial commit

00_Globale_Richtlinien/Planung/Code_Style.md

@@ -0,0 +1,251 @@
+# 🎨 Code Style Richtlinien für das KI-Cluster
+
+## 1. Ziel
+Diese Richtlinie definiert den **einheitlichen Schreib- und Formatierungsstil** für alle Python-Module im KI-Cluster.  
+Ziel ist, dass automatisch generierter, manuell geschriebener und überarbeiteter Code **gleich aussieht**, leicht lesbar und wartbar bleibt,  
+und durch den Builder-Agent problemlos validiert werden kann.
+
+---
+
+## 2. Allgemeine Formatierung
+
+| Regel | Wert |
+|--------|------|
+| **Einrückung** | 4 Leerzeichen (keine Tabs) |
+| **Zeilenlänge** | max. 100 Zeichen |
+| **Kodierung** | UTF-8 |
+| **Dateiende** | genau eine Leerzeile |
+| **Kommentare** | Deutsch oder Englisch, klar und knapp |
+| **Anführungszeichen** | doppelte (`"Text"`) bevorzugt |
+| **Importreihenfolge** | Standardbibliothek → Drittpakete → interne Module |
+| **Trennung** | jeweils 1 Leerzeile zwischen Funktionsdefinitionen |
+
+Beispiel:
+```python
+import os
+import sys
+
+import requests
+
+from utils.api_client import APIClient
+```
+
+---
+
+## 3. Leerzeilen & Struktur
+
+- 2 Leerzeilen zwischen Klassen  
+- 1 Leerzeile zwischen Methoden oder Funktionen  
+- Keine mehrfachen Leerzeilen  
+- Eine Leerzeile am Ende jeder Datei
+
+Beispiel:
+```python
+class RouterModule:
+    pass
+
+
+class APIModule:
+    pass
+```
+
+---
+
+## 4. Docstrings
+
+Alle Module, Klassen und Funktionen müssen **Docstrings** besitzen.  
+Empfohlenes Format: **Google Style**.
+
+Beispiel (Funktion):
+```python
+def load_config(file_path: str) -> dict:
+    """Lädt eine YAML-Konfigurationsdatei.
+
+    Args:
+        file_path (str): Pfad zur Konfigurationsdatei.
+
+    Returns:
+        dict: Geladene Konfiguration.
+    """
+    pass
+```
+
+Beispiel (Klasse):
+```python
+class APIClient:
+    """Kommuniziert mit REST-Endpunkten des Systems.
+
+    Attributes:
+        base_url (str): Zieladresse des Endpunkts.
+    """
+
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+```
+
+---
+
+## 5. Kommentare
+
+Kommentare sollen **nicht beschreiben, was der Code tut**,  
+sondern **warum er es tut**.
+
+Beispiel:
+```python
+# Schreibt Cache-Datei nur neu, wenn sich Inhalte geändert haben
+if new_hash != old_hash:
+    write_cache()
+```
+
+Regeln:
+- Kein redundanter Kommentar wie `# Zählt i um 1 hoch`
+- Kommentare beginnen mit Großbuchstaben, enden ohne Punkt.
+- Längere Erklärungen über mehrere Zeilen mit `#` beginnen.
+
+---
+
+## 6. Typannotationen
+
+Alle Funktionen und Methoden müssen Typannotationen besitzen.  
+Beispiel:
+```python
+def send_message(target: str, data: dict) -> bool:
+    ...
+```
+
+Generische Typen werden importiert:
+```python
+from typing import Any, Optional, List, Dict
+```
+
+---
+
+## 7. Konstanten & Variablen
+
+| Typ | Schreibweise | Beispiel |
+|------|----------------|-----------|
+| Konstanten | `UPPER_CASE` | `MAX_CONNECTIONS = 10` |
+| Variablen | `snake_case` | `active_modules = []` |
+| Klassenattribute | `self.attribute_name` | `self.router_url = ""` |
+
+---
+
+## 8. Imports
+
+- Keine relativen Importe (`from .core import ...` → ❌)  
+- Immer absolute Importe mit vollständigem Pfad ab Projektwurzel  
+- Imports werden alphabetisch sortiert
+
+Beispiel:
+```python
+from utils.api_client import APIClient
+from utils.logging_setup import get_logger
+```
+
+---
+
+## 9. Fehlerbehandlung
+
+- Fehler **explizit abfangen** (kein `except:` ohne Typ)  
+- Logging statt `print()`  
+- Möglichst spezifische Fehlertypen verwenden
+
+Beispiel:
+```python
+try:
+    response = requests.get(url)
+    response.raise_for_status()
+except requests.ConnectionError as e:
+    logger.error(f"Verbindungsfehler: {e}")
+```
+
+---
+
+## 10. Linter & Formatter
+
+- **Linter:** `flake8`  
+- **Formatter:** `black`  
+- **Docstring-Prüfer:** `pydocstyle`  
+- **Typprüfung:** `mypy`
+
+Beispiel-Aufruf:
+```bash
+flake8 src/
+black src/ --line-length 100
+pydocstyle src/
+mypy src/
+```
+
+Der Builder-Agent führt diese Werkzeuge automatisch aus, bevor Code akzeptiert wird.
+
+---
+
+## 11. Logging-Stil
+
+- Nutze das globale Logging-Setup (`logging_setup.py`)  
+- Präfix mit Modulnamen und Funktionskontext  
+- Levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+Beispiel:
+```python
+self.logger.info("[RouterModule] Verbindung erfolgreich hergestellt.")
+self.logger.error("[APIModule] Fehler bei der Verarbeitung.")
+```
+
+---
+
+## 12. Formatierung von Datenstrukturen
+
+| Struktur | Beispiel |
+|-----------|-----------|
+| Liste | `users = ["Alice", "Bob", "Eve"]` |
+| Dictionary | `config = {"host": "localhost", "port": 5000}` |
+| Mehrzeilig (mit Einrückung) | ```python
+data = {
+    "name": "Cluster",
+    "modules": ["Router", "Memory", "API"]
+}
+``` |
+
+---
+
+## 13. Unit Tests
+
+- Testdateien: `test_<ziel>.py`  
+- Testmethoden: `test_<funktion>`  
+- Verwende `pytest`  
+- Kein direkter `print()` in Tests  
+- Tests sind deterministisch (keine Zufallswerte ohne Seeds)
+
+Beispiel:
+```python
+def test_load_config(tmp_path):
+    config_file = tmp_path / "config.yaml"
+    config_file.write_text("test: true")
+    result = load_config(config_file)
+    assert result["test"] is True
+```
+
+---
+
+## 14. Builder-Agent Anforderungen
+
+Damit automatisch generierter Code kompatibel bleibt, gilt:
+- Builder muss diese Formatierung exakt einhalten  
+- Keine abweichenden Imports oder Zeilenlängen  
+- Kommentare müssen klar und in Deutsch oder Englisch sein  
+- Docstrings **immer vollständig** (Args, Returns)
+
+---
+
+## 15. Zusammenfassung
+
+Durch die konsequente Anwendung dieses Code-Stils wird erreicht:
+- Einheitlicher Look & Feel des gesamten Projekts  
+- Nahtlose Integration neuer Module durch den Builder-Agent  
+- Lesbarkeit, Wartbarkeit und Nachvollziehbarkeit auf Systemebene
+
+---
+
+© 2025 – KI-Cluster Homelab Architektur  
+Autor: *[Dein Name oder Alias]*