# Konventionen

Sprache, IDs, Package-Struktur, Naming.

## Sprache

- **Code:** Englisch — Klassen, Methoden, Felder, Enums, Package-Namen, Javadoc.
- **YAML:** Englisch — Keys, IDs, alle Texte (descriptions, dialogue, readText, etc.).
- **Doku-Prose** (`docs/*.md`): Deutsch — Diskussion mit dem Entwickler, keine Spec für Korrektoren.

## IDs

Slugs, keine UUIDs. Begründung in [item-model.md](item-model.md) und [yaml-schemas.md](yaml-schemas.md).

| Regel | Beispiel | Gegenbeispiel |
|---|---|---|
| nur kleinbuchstaben | `kitchen`, `letter` | `Kitchen`, `LETTER` |
| ASCII, keine Umlaute | `cellar`, `kueche` schlecht | `keller` gut, `küche` schlecht |
| Mehrwortig: snake_case | `oil_lamp`, `old_man` | `oilLamp`, `old-man`, `oil lamp` |
| keine führende Ziffer | `key1` | `1key` |
| nur `[a-z0-9_]` | `key2` | `key#2`, `key@2` |

Regex zur Validierung im `WorldValidator`:

```
^[a-z][a-z0-9_]*$
```

Geltungsbereich: id ist eindeutig **innerhalb seiner Entitätsart**. Ein Item und ein NPC dürfen `lamp` heißen (nicht empfohlen, aber technisch erlaubt).

## Package-Struktur

```
thb.jeanluc.adventure
├── model
│   ├── Direction
│   ├── Room
│   ├── Player
│   ├── Npc
│   └── item              <- eigener Subpackage wegen Hierarchie
│       ├── Item (abstract)
│       ├── ReadableItem
│       ├── SwitchableItem
│       └── PlainItem
├── io
├── command
├── game
└── loader
    └── dto
```

**Wann ein Subpackage:** wenn eine Klassenfamilie ≥ 3 Klassen umfasst und eine eigene Abstraktion bildet (`item`, evtl. später `command.impl`). Sonst flach lassen.

## Naming

Java-Standard:
- Klassen: `UpperCamelCase`
- Methoden, Felder, Parameter: `lowerCamelCase`
- Konstanten: `UPPER_SNAKE_CASE`
- Packages: `lowercase`, ohne Underscores wenn möglich

YAML:
- Keys: `lowerCamelCase` (`startRoom`, `readText`, `initialState`) — passt zu Jackson-Default-Mapping auf Java-Felder
- IDs: siehe oben

## Javadoc

Pflicht laut Aufgabenstellung **an Klassen, Methoden, und Instanzvariablen**. Auch bei Lombok-Feldern wenn sie `@Getter`-exposed sind.

Keep it sachlich — was tut die Klasse/Methode, nicht wie. Keine Geschichten erzählen.

## Tests

- Unit-Tests pro Domain-Klasse: `RoomTest`, `PlayerTest`, `ItemTest` etc.
- Integration-Tests für Loader: `WorldLoaderTest` mit `src/test/resources/world/`-Fixtures
- Naming: `methodName_condition_expectedResult` — z.B. `addExit_withNewDirection_storesNeighbour`

## Lombok-Cheatsheet

| Annotation | Wozu |
|---|---|
| `@Getter` | Getter für alle Felder |
| `@RequiredArgsConstructor` | Konstruktor nur für finals ohne Initializer |
| `@SuperBuilder` | Builder über Vererbung (statt `@Builder`) |
| `@Slf4j` | `log`-Field für SLF4J |
| `@ToString` | Nur wenn aussagekräftig — sonst weglassen |

**Vermeiden:** `@Data` (zu viel auf einmal, generiert `equals/hashCode` was bei Room/Player unerwünscht ist).