251 lines
5.5 KiB
Markdown
251 lines
5.5 KiB
Markdown
# 🎨 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]* |