Code Guidelines

Coding guidelines for the JayDee development team. These guidelines exist to keep our codebase clean, consistent, and easy for everyone on the team to read and work with.

Core principle: KISS — Keep It Simple and Stupid. Simple, clean, readable code is always the goal. If a solution feels complicated, step back and find a simpler way.

1. General Mindset

Write code as if the next person reading it has never seen the project before. They should be able to understand what's happening without digging through five other files.

• Prefer straightforward solutions over clever ones. Clever code is hard to debug.
• Only build what was asked for. No speculative features, no "while I'm here" improvements.
• If something is unclear, ask. Don't guess and build on assumptions.
• When you change existing code, match the style that's already there. Consistency within a file matters more than personal preference.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1.1 Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

1.2 Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

1.3 Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

1.4 Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "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"

For multi-step tasks, state a brief plan:

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

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

2. Naming Conventions

BSH uses a mixed naming style depending on context. Follow these patterns:

Context	Convention	Example
PHP Controllers / Classes	PascalCase	CustomerController, OrderService
PHP/JS Variables	camelCase	$customerName, let orderTotal
Function parameters, DB-related variables	snake_case	$from_attr, $to_attr
Database tables	snake_case with prefixes	lu_gender, admin_users
Database columns	type-prefixed snake_case	str_name, dtm_created, bol_active
React/Vue Components	PascalCase	CustomerList, OrderForm
Blade views / partials	kebab-case	customer-list.blade.php
CSS classes	kebab-case	order-summary, nav-item

When in doubt: controllers and classes get PascalCase, variables get camelCase, and anything touching the database gets snake_case.

3. Git Conventions

Branching

Branch names follow the pattern: 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 — your name or short identifier
• stack — the technology area (laravel, react, shopware, database, etc.)
• part — a short description of what you're working on

Commit Messages

Every commit message starts with a prefix that describes the type of change:

Prefix	Use for
FIX:	Bug fixes
TASK:	New features, improvements, general work
DOCS:	Documentation changes

Examples:

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

Keep commit messages short but descriptive enough that someone reading the git log understands what changed and why.

4. Database Conventions

These conventions apply across both PostgreSQL and MySQL projects.

Table Prefixes

Prefix/Suffix	Purpose	Example
admin_	Administrative functions	admin_settings
lu_	Lookup/reference data	lu_gender, lu_country
_join suffix	Many-to-many relationships	customer_product_join
bs_	Legacy employee records (deprecated)	bs_employees

Federated sources keep their own prefixes: bj_ (Bluejects), ds_ (Dental.Shop), wds_ (WDS-App), done_ (Done), qmds_ (QM-Bausteine).

Column Type Prefixes

Always prefix columns with their data type:

Prefix	Type	Example
str_	varchar/text	str_first_name
dtm_	date/time	dtm_appointment
_at suffix	timestamps	created_at, updated_at
json_	JSON fields	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 Naming

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

Database Objects

Object	Prefix	Example
Procedures	prc_	prc_sync_customers
Functions	fnc_	fnc_calculate_total
Events	event_	event_daily_cleanup
Views	view_	view_active_orders

5. Laravel / PHP

Keep it practical — whatever works, as long as it's simple and fast.

• Use Eloquent for database queries. The ORM is there to make things readable and safe.
• Use Form Requests when validation gets complex. For simple checks, inline validation is fine.
• Keep controllers lean. If a method grows beyond ~30 lines, consider extracting logic into a service class — but only if it actually improves readability.
• Use Laravel's built-in features (collections, helpers, middleware) before reaching for custom solutions.
• Follow PSR-12 for PHP code style.

Blade & Livewire

• Keep Blade templates clean and readable. Extract repeated markup into components or partials.
• Use Livewire for interactive UI elements that don't need a full SPA. It keeps things in the Laravel ecosystem and avoids unnecessary JavaScript complexity.
• Name Blade views and partials in kebab-case: customer-list.blade.php, order-form.blade.php.
• Keep Livewire components focused on one interaction. If a component handles too many things, split it up.

6. Frontend

React (default for TypeScript projects, Docusaurus)

• Use functional components with hooks.
• Keep components focused — one clear responsibility each.
• Colocate related files (component, styles, types) when it makes sense.

Vue (Shopware projects)

• Follow Shopware's conventions and component patterns.
• Use Composition API for new components.
• Respect the Shopware plugin architecture — don't fight the framework.

General Frontend

• Keep component files short. If a component exceeds ~150 lines, look for ways to split it.
• Name components clearly so you can tell what they do without opening the file.

7. Things You Must Never Do

These rules exist because they've caused real problems. No exceptions.

• Never use raw SQL queries. Always use the ORM (Eloquent) or the query builder. Raw SQL is a security risk and hard to maintain.
• Never put secrets in code. No API keys, passwords, tokens, or credentials anywhere in source files. Use .env files and config — that's what they're for.
• Never commit login credentials. Not in code, not in comments, not in config files that get committed. If you see credentials in a repo, flag it immediately.
• Never load external resources from CDNs or remote URLs in production. All assets (JS, CSS, fonts, images) must be served from our own servers. Download and bundle them locally. This is about reliability and control — if an external CDN goes down, our apps should still work.
• Never skip .gitignore. Make sure .env, vendor/, node_modules/, and build artifacts are never committed.

8. Code Quality Basics

• Remove dead code. Don't comment it out "just in case" — that's what git history is for.
• Keep functions short and focused. If you need a comment to explain what a block does, it's probably better as its own function with a descriptive name.
• Use meaningful variable names. $data, $temp, $x are almost never acceptable.
• Handle errors where they matter, but don't wrap everything in try-catch blocks for the sake of it.
• When you touch a file, leave it at least as clean as you found it — but don't go on a refactoring spree in an unrelated area.

9. Making Changes to Existing Code

When working on existing BSH code:

• Read the surrounding code first. Understand the patterns in use before changing anything.
• Make surgical changes — only touch what's needed for your task.
• If you spot something broken or messy nearby, mention it. Don't silently fix unrelated things in the same change.
• Match the existing file's style. If the file uses one pattern and you prefer another, the file wins.