Code Guidelines

Coding Guidelines für das JayDee-Development-Team. Diese Regeln sollen dafür sorgen, dass unsere Codebases sauber, konsistent und für alle im Team leicht lesbar bleiben.

Kernprinzip: KISS - Keep It Simple and Stupid. Einfacher, sauberer, lesbarer Code ist immer das Ziel. Wenn sich eine Lösung kompliziert anfühlt, einen Schritt zurückgehen und den einfacheren Weg suchen.

1. Allgemeine Denkweise

Schreibe Code so, als hätte die nächste Person das Projekt noch nie gesehen. Sie sollte verstehen können, was passiert, ohne fünf andere Dateien öffnen zu müssen.

• Bevorzuge geradlinige Lösungen statt cleverer Tricks. Cleverer Code ist schwer zu debuggen.
• Baue nur das, was angefragt wurde. Keine spekulativen Features und keine "wenn ich schon dabei bin"-Verbesserungen.
• Wenn etwas unklar ist, frage nach. Nicht raten und auf Annahmen aufbauen.
• Wenn du bestehenden Code änderst, passe dich dem vorhandenen Stil an. Konsistenz innerhalb einer Datei ist wichtiger als persönliche Vorlieben.

Trade-off: Diese Guidelines bevorzugen Vorsicht gegenüber Geschwindigkeit. Bei trivialen Aufgaben ist Augenmaß gefragt.

1.1 Think Before Coding

Nichts annehmen. Verwirrung nicht verstecken. Trade-offs sichtbar machen.

Vor der Implementierung:

• Annahmen explizit benennen. Bei Unsicherheit nachfragen.
• Wenn mehrere Interpretationen möglich sind, diese nennen - nicht still eine auswählen.
• Wenn ein einfacherer Ansatz existiert, darauf hinweisen. Bei Bedarf freundlich widersprechen.
• Wenn etwas unklar ist, stoppen. Benennen, was verwirrt. Nachfragen.

1.2 Simplicity First

So wenig Code wie möglich, um das Problem zu lösen. Nichts Spekulatives.

• Keine Features über die Anfrage hinaus.
• Keine Abstraktionen für Single-Use-Code.
• Keine "Flexibilität" oder "Konfigurierbarkeit", die nicht verlangt wurde.
• Kein Error Handling für unmögliche Szenarien.
• Wenn du 200 Zeilen schreibst und es auch 50 sein könnten, umschreiben.

Frage dich: "Würde ein Senior Engineer sagen, dass das überkompliziert ist?" Wenn ja, vereinfachen.

1.3 Surgical Changes

Nur das anfassen, was du wirklich musst. Nur den eigenen Schaden aufräumen.

Beim Bearbeiten bestehenden Codes:

• Benachbarten Code, Kommentare oder Formatierung nicht "verbessern".
• Nichts refactoren, was nicht kaputt ist.
• Den vorhandenen Stil matchen, auch wenn du es anders lösen würdest.
• Wenn dir toter Code auffällt, erwähne ihn - aber lösche ihn nicht.

Wenn deine Änderungen Orphans erzeugen:

• Imports/Variablen/Funktionen entfernen, die durch deine Änderungen ungenutzt wurden.
• Bereits vorher vorhandenen toten Code nicht ohne Auftrag löschen.

Der Test: Jede geänderte Zeile muss sich direkt auf die Nutzeranforderung zurückführen lassen.

1.4 Goal-Driven Execution

Erfolgskriterien definieren. In Schleifen arbeiten, bis verifiziert ist, dass es funktioniert.

Aufgaben in überprüfbare Ziele verwandeln:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

Für mehrstufige Aufgaben eine kurze Planung formulieren:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Starke Erfolgskriterien erlauben eigenständige Schleifen. Schwache Kriterien wie "make it work" erzeugen ständigen Klärungsbedarf.

2. Naming Conventions

BSH nutzt je nach Kontext gemischte Benennungsschemata. Folge diesen Mustern:

Kontext	Konvention	Beispiel
PHP Controller / Klassen	PascalCase	CustomerController, OrderService
PHP/JS Variablen	camelCase	$customerName, let orderTotal
Funktionsparameter, DB-nahe Variablen	snake_case	$from_attr, $to_attr
Datenbanktabellen	snake_case mit Präfixen	lu_gender, admin_users
Datenbankspalten	typpräfixiertes snake_case	str_name, dtm_created, bol_active
React/Vue-Komponenten	PascalCase	CustomerList, OrderForm
Blade Views / Partials	kebab-case	customer-list.blade.php
CSS-Klassen	kebab-case	order-summary, nav-item

Im Zweifel gilt: Controller und Klassen bekommen PascalCase, Variablen camelCase und alles mit Datenbankbezug snake_case.

3. Git-Konventionen

Branching

Branch-Namen folgen dem Muster: user/stack/part

git checkout -b juri/laravel/customer-sync
git checkout -b anna/react/order-dashboard
git checkout -b max/shopware/product-import

• user - dein Name oder ein kurzes Kürzel
• stack - der Technologie-Bereich (laravel, react, shopware, database usw.)
• part - eine kurze Beschreibung, woran gearbeitet wird

Commit Messages

Jede Commit Message startet mit einem Präfix, das die Art der Änderung beschreibt:

Präfix	Verwenden für
FIX:	Bugfixes
TASK:	Neue Features, Verbesserungen, allgemeine Arbeit
DOCS:	Dokumentationsänderungen

Beispiele:

FIX: resolve customer sync timeout on large datasets
TASK: add order export endpoint for Dental.Shop
DOCS: update database naming conventions

Commit Messages kurz halten, aber so beschreibend, dass im Git-Log klar ist, was geändert wurde und warum.

4. Datenbank-Konventionen

Diese Konventionen gelten sowohl für PostgreSQL- als auch für MySQL-Projekte.

Tabellen-Präfixe

Präfix/Suffix	Zweck	Beispiel
admin_	Administrative Funktionen	admin_settings
lu_	Lookup-/Referenzdaten	lu_gender, lu_country
_join Suffix	Many-to-many-Beziehungen	customer_product_join
bs_	Legacy-Mitarbeiterdaten (deprecated)	bs_employees

Föderierte Quellen behalten ihre eigenen Präfixe: bj_ (Bluejects), ds_ (Dental.Shop), wds_ (WDS-App), done_ (Done), qmds_ (QM-Bausteine).

Spalten-Typ-Präfixe

Spalten immer mit ihrem Datentyp präfixieren:

Präfix	Typ	Beispiel
str_	varchar/text	str_first_name
dtm_	date/time	dtm_appointment
_at Suffix	Timestamps	created_at, updated_at
json_	JSON-Felder	json_config
bin_	Binary	bin_document
int_	Integer	int_quantity
dec_	Decimal	dec_price
bol_	Boolean	bol_active
id	Primary Key	id
_id Suffix	Foreign Key	customer_id

Index-Namen

• Standard: {table}_{column}_index
• Foreign Key: {table}_{column}_foreign
• Unique: {table}_{columns}_unique
• Full-text: {table}_{column}_fulltext

Datenbank-Objekte

Objekt	Präfix	Beispiel
Procedures	prc_	prc_sync_customers
Functions	fnc_	fnc_calculate_total
Events	event_	event_daily_cleanup
Views	view_	view_active_orders

5. Laravel / PHP

Pragmatisch bleiben - was funktioniert, solange es einfach und schnell bleibt.

• Eloquent für Datenbankabfragen verwenden. Das ORM ist da, um Dinge lesbar und sicher zu machen.
• Form Requests verwenden, wenn Validierung komplex wird. Für einfache Checks reicht Inline-Validierung.
• Controller schlank halten. Wenn eine Methode deutlich über ~30 Zeilen wächst, kann das Auslagern in eine Service-Klasse sinnvoll sein - aber nur, wenn es die Lesbarkeit tatsächlich verbessert.
• Erst Laravels eingebaute Features nutzen (Collections, Helpers, Middleware), bevor eigene Lösungen gebaut werden.
• PSR-12 als PHP-Code-Style einhalten.

Blade & Livewire

• Blade-Templates sauber und lesbar halten. Wiederholtes Markup in Komponenten oder Partials auslagern.
• Livewire für interaktive UI-Elemente nutzen, die kein vollständiges SPA brauchen. Das hält die Dinge im Laravel-Ökosystem und vermeidet unnötige JavaScript-Komplexität.
• Blade Views und Partials in kebab-case benennen: customer-list.blade.php, order-form.blade.php.
• Livewire-Komponenten auf eine Interaktion fokussieren. Wenn eine Komponente zu viele Dinge macht, aufteilen.

6. Frontend

React (Default für TypeScript-Projekte, Docusaurus)

• Funktionale Komponenten mit Hooks verwenden.
• Komponenten fokussiert halten - eine klare Verantwortung pro Komponente.
• Verwandte Dateien (Komponente, Styles, Types) zusammenhalten, wenn es sinnvoll ist.

Vue (Shopware-Projekte)

• Den Shopware-Konventionen und Komponentenmustern folgen.
• Für neue Komponenten die Composition API nutzen.
• Die Shopware-Plugin-Architektur respektieren - nicht gegen das Framework arbeiten.

Allgemeines Frontend

• Komponenten-Dateien kurz halten. Wenn eine Komponente deutlich über ~150 Zeilen geht, nach sinnvollen Aufteilungen suchen.
• Komponenten klar benennen, damit man versteht, was sie tun, ohne sie erst öffnen zu müssen.

7. Dinge, die du niemals tun darfst

Diese Regeln existieren, weil sie bereits echte Probleme verursacht haben. Keine Ausnahmen.

• Niemals Raw SQL Queries verwenden. Immer ORM (Eloquent) oder Query Builder nutzen. Raw SQL ist ein Sicherheitsrisiko und schwer wartbar.
• Niemals Secrets in Code ablegen. Keine API Keys, Passwörter, Tokens oder Credentials in Source Files. Dafür sind .env-Dateien und Config da.
• Niemals Login-Daten committen. Weder im Code noch in Kommentaren oder eingecheckten Config-Dateien. Wenn du Credentials in einem Repo siehst, sofort markieren.
• Niemals externe Ressourcen per CDN oder Remote-URL in Production laden. Alle Assets (JS, CSS, Fonts, Bilder) müssen von unseren eigenen Servern kommen. Lokal herunterladen und bündeln. Das geht um Zuverlässigkeit und Kontrolle.
• Niemals .gitignore vernachlässigen. Sicherstellen, dass .env, vendor/, node_modules/ und Build-Artefakte nie committed werden.

8. Code-Qualitäts-Basics

• Toten Code entfernen. Nicht auskommentieren "für später" - dafür gibt es Git-History.
• Funktionen kurz und fokussiert halten. Wenn du einen Kommentar brauchst, um einen Block zu erklären, ist er oft besser als eigene Funktion mit aussagekräftigem Namen aufgehoben.
• Aussagekräftige Variablennamen nutzen. $data, $temp, $x sind fast nie akzeptabel.
• Fehler dort behandeln, wo es relevant ist, aber nicht aus Prinzip alles in Try-Catch-Blöcke packen.
• Wenn du eine Datei anfasst, hinterlasse sie mindestens so sauber, wie du sie vorgefunden hast - aber starte keinen Refactoring-Ausflug in einem anderen Bereich.

9. Änderungen an bestehendem Code

Beim Arbeiten an bestehendem BSH-Code:

• Erst den umgebenden Code lesen. Verstehen, welche Muster bereits verwendet werden, bevor etwas geändert wird.
• Chirurgische Änderungen machen - nur das anfassen, was für die Aufgabe nötig ist.
• Wenn dir in der Nähe etwas Defektes oder Unsauberes auffällt, erwähne es. Nicht stillschweigend im selben Change mit reparieren.
• Den Stil der vorhandenen Datei matchen. Wenn die Datei ein bestimmtes Muster nutzt und du ein anderes bevorzugst, gewinnt die Datei.