201 lines
4.8 KiB
Markdown
201 lines
4.8 KiB
Markdown
# 🧩 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]* |