coding-style

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.

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)

Core Principles

KISS (Keep It Simple, Stupid): Simplest solution that works. Avoid over-engineering. No premature optimization. Easy to understand beats clever code.

DRY (Don't Repeat Yourself): Extract common logic. Create reusable components. Share utilities. Avoid copy-paste programming.

YAGNI (You Aren't Gonna Need It): Don't build before needed. Avoid speculative generality. Add complexity only when required.

Naming Conventions

Descriptive names: Variable and function names should be self-documenting. Choose clear over clever.

// Good: Descriptive
const marketSearchQuery = "election";
const isUserAuthenticated = true;

// Bad: Unclear
const q = "election";
const flag = true;

Function naming: Use verb-noun pattern. Names read like actions.

// Good
async function fetchMarketData(id: string) {}
function calculateSimilarity(a: number[], b: number[]) {}
function isValidEmail(email: string): boolean {}

// Bad
async function market(id: string) {}
function similarity(a, b) {}