style

Coding Style

Surgical Changes

Every changed line must trace directly back to the user's request. Adjacent "improvements" inflate the diff, make review harder, and cause unintended regressions.

MUST NOT

• "Improve" neighboring code, formatting, or comments along the way.
• Refactor something that is not broken.
• Change existing style to your own preference (quotes, indentation, line breaks, import order).
• Add type hints, docstrings, or comments that were not asked for.
• Slip in a new abstraction, flag, setting, or option nobody requested.
• Delete unrelated dead code — mention it and propose it as separate work.
• Mix two purposes into one commit or PR.

MUST

• Match the existing style, naming, and formatting exactly.
• Clean up only the imports, variables, and functions your own change orphaned.
• State "behavior is unchanged" explicitly when the refactor is behavior-preserving.

Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate:

// WRONG: Mutation
function updateUser(user, name) {
  user.name = name  // MUTATION!
  return user
}

// CORRECT: Immutability
function updateUser(user, name) {
  return {
    ...user,
    name
  }
}

File Organization

MANY SMALL FILES > FEW LARGE FILES:

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

Error Handling

ALWAYS handle errors comprehensively:

try {
  const result = await riskyOperation()
  return result
} catch (error) {
  console.error('Operation failed:', error)
  throw new Error('Detailed user-friendly message')
}

Input Validation

ALWAYS validate user input:

import { z } from 'zod'

const schema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0).max(150)
})

const validated = schema.parse(input)

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
• No mutation (immutable patterns used)