code-style-principles

name	code-style-principles
description	ACTIVATE whenever writing or modifying production code in src/. ACTIVATE for code review, formatting questions, or 'coding standards'. Covers cross-language code style: control-structure spacing, early-return pattern, continue-vs-if/else in loops, explicit (non-truthy/falsy) checks, flattening nested null checks, parameter ordering. These rules go BEYOND standard linters. Language-specific syntax (no-empty in PHP, template literals in TS, nowdoc, optional chaining vs nullsafe) lives in php-code-conventions / ts-code-conventions.
version	1.0

Code Style — Cross-Language Principles

The rules below are language-agnostic. Syntax-specific examples (nullsafe ?->, optional chaining ?., no-empty(), nowdoc, template literals) live in:

• php-code-conventions
• ts-code-conventions

These conventions go beyond standard linters (PSR-12/PER, eslint/prettier). They encode the project's house style.

1. Control-Structure Spacing

Always add a blank line before AND after control structures (if, for, foreach/for...of, while, switch) when they are not at the start or end of the enclosing block.

Exception: no blank line at start or end of a method/function/block.

Why: visual separation between sequential statements and branching/looping logic.

2. Early-Return Pattern

Always use early return to handle edge cases and invalid conditions first. Main logic stays at base indentation.

• Reduces nesting.
• Clarifies intent (edge cases handled upfront).
• Add a blank line before the return when preceded by other statements.

3. If-Continue Pattern in Loops

continue in a loop is the equivalent of early-return in a function.

• Use continue only when the exit condition is simple and the main processing is more complex.
• When both branches have comparable complexity, prefer a classic if/else for readability.
• Add a blank line before continue / return / break / throw when preceded by other statements.

4. Flatten Nested Null Checks

Replace nested null-guards with the language's null-propagation operator (PHP: ?->, TS: ?., Kotlin: ?., Swift: ?.).

For absent values with a default, use the null-coalescing operator (PHP: ??, TS: ??, …).

Criterion: if you nest more than one if (x !== null), use null-propagation.

5. Explicit Checks Over Implicit Truthy/Falsy

Use explicit comparisons instead of relying on language coercion.

• Arrays / collections: compare to empty (=== [], .length > 0) — not truthy.
• Strings: compare to '' (or use length).
• Null/undefined: compare to null / undefined explicitly.

Exception: booleans can be checked directly (if (isValid)).

Why: implicit truthy/falsy hides type bugs and gives unstable results across languages (and even across the same language: PHP empty(), JS coercion).

6. Parameter Ordering

Constructors / function signatures: mandatory parameters before optional / nullable.

Within each group, the language's natural ordering applies (e.g. promoted properties in PHP, default values in TS).

7. Comments — Justify or Delete

Write a comment only when the code cannot speak for itself. A comment earns its place if it surfaces something the code does not:

• Hidden complexity — a non-obvious algorithm, a workaround, a !important / specificity hack, an ordering constraint.
• Business / domain rule — the why behind a magic value or branch (e.g. "French IBAN length = 27").
• A decision that would otherwise look wrong — why a line is disabled, why a framework default is overridden.

Delete any comment that restates the code without adding value:

// AVOID — reproduces the code
// Uppercase the IBAN and strip whitespace
return strtoupper(preg_replace('/\s+/', '', $iban));

// AVOID — restates the name
/** Extra HTML attributes applied to the wrapper. */
public array $wrapperAttributes = [];

// CORRECT — surfaces a non-obvious rule
// !important: beat Bootstrap's :valid border (empty boxes are HTML5-valid)
border-color: $danger !important;

Type annotations are not prose comments: keep @var / @return / @param when they add type information a tool or reader needs — they are not subject to this rule.

Heuristic: if deleting the comment loses no information a competent reader couldn't get from the code in seconds, delete it.

Quick Reference

Rule	Principle
Control-structure spacing	Blank line before AND after if/for/while/switch (except start/end of block)
Early return	Edge cases first, main logic at base indentation
Continue vs if/else	continue only when exit is simple and main is complex
Flatten null checks	Use null-propagation operator instead of nested if
Explicit checks	No implicit truthy/falsy — compare to empty / null explicitly
Parameter ordering	Mandatory before optional
Comments	Only for hidden complexity / business rule; delete anything that restates the code