Coding Style

Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate existing ones:

// Pseudocode
WRONG:  modify(original, field, value) → changes original in-place
CORRECT: update(original, field, value) → returns new copy with change

Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.

Core Principles

KISS (Keep It Simple)

• Prefer the simplest solution that actually works
• Avoid premature optimization
• Optimize for clarity over cleverness

DRY (Don't Repeat Yourself)

• Extract repeated logic into shared functions or utilities
• Avoid copy-paste implementation drift
• Introduce abstractions when repetition is real, not speculative

YAGNI (You Aren't Gonna Need It)

• Do not build features or abstractions before they are needed
• Avoid speculative generality
• Start simple, then refactor when the pressure is real

File Organization

MANY SMALL FILES > FEW LARGE FILES:

• High cohesion, low coupling
• 200-400 lines typical, 800 max
• Extract utilities from large modules
• Organize by feature/domain, not by type

Error Handling

ALWAYS handle errors comprehensively:

• Handle errors explicitly at every level
• Provide user-friendly error messages in UI-facing code
• Log detailed error context on the server side
• Never silently swallow errors

Input Validation

ALWAYS validate at system boundaries:

• Validate all user input before processing
• Use schema-based validation where available
• Fail fast with clear error messages
• Never trust external data (API responses, user input, file content)

Naming Conventions

• Variables and functions: camelCase with descriptive names
• Booleans: prefer is, has, should, or can prefixes
• Interfaces, types, and components: PascalCase
• Constants: UPPER_SNAKE_CASE
• Custom hooks: camelCase with a use prefix

Code Smells to Avoid

Deep Nesting

Prefer early returns over nested conditionals once the logic starts stacking.

Magic Numbers

Use named constants for meaningful thresholds, delays, and limits.

Long Functions

Split large functions into focused pieces with clear responsibilities.

Code Quality Checklist

Before marking work complete:

• Code is readable and well-named
• Functions are small (<50 lines)
• Files are focused (<800 lines)
• No deep nesting (>4 levels)
• Proper error handling
• No hardcoded values (use constants or config)
• No mutation (immutable patterns used)