5.5 KiB
🎨 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]