Jean-Luc Makiola
83643a192f
Walking skeleton through Swing GUI: YAML-driven world (4 rooms, 4 items, 1 NPC), HashMap command dispatch with parser, three-tier item hierarchy (readable / switchable / plain), and end-to-end NPC give/receive flow. 67 tests green.
89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
# 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).
|