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

🎨 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:

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:

class RouterModule:
    pass


class APIModule:
    pass

---

4. Docstrings

Alle Module, Klassen und Funktionen müssen Docstrings besitzen.
Empfohlenes Format: Google Style.

Beispiel (Funktion):

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):

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:

# 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:

def send_message(target: str, data: dict) -> bool:
    ...

Generische Typen werden importiert:

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:

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:

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:

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:

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]