Coding Standards

Coding Standards & Best Practices

Universal coding standards applicable across all projects.

Code Quality Principles

• Readability First: Clear names, self-documenting code
• KISS: Simplest solution, avoid over-engineering
• DRY: Extract common logic, reusable components
• YAGNI: Build only what's needed

TypeScript/JavaScript Standards

Immutability Pattern (CRITICAL)

// ✅ Spread operator
const updated = { ...user, name: 'New' }
const items = [...list, newItem]

// ❌ Direct mutation
user.name = 'New'
items.push(newItem)

Error Handling

async function fetchData(url: string) {
  try {
    const response = await fetch(url)
    if (!response.ok) throw new Error(`HTTP ${response.status}`)
    return await response.json()
  } catch (error) {
    throw new Error('Failed to fetch')
  }
}

Async/Await & Type Safety

// ✅ Parallel execution
const [users, markets] = await Promise.all([fetchUsers(), fetchMarkets()])

// ✅ Proper types
interface Market { id: string; status: 'active' | 'resolved' }

// ❌ Using 'any' or sequential when unnecessary

React Best Practices

Component Structure

interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
}

export function Button({ children, onClick, disabled = false }: ButtonProps) {
  return <button disabled={disabled}>{children}</button>
}

Custom Hooks & State

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)
  useEffect(() => {
    const handler = setTimeout(() => setDebouncedValue(value), delay)
    return () => clearTimeout(handler)
  }, [value, delay])
  return debouncedValue
}

// ✅ Functional update | ❌ Direct reference (stale)
setCount(prev => prev + 1) | setCount(count + 1)

API Design Standards

REST API Conventions

GET/POST/PUT/PATCH/DELETE /api/markets/:id

Response Format & Validation

interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
}

import { z } from 'zod'
const Schema = z.object({ name: z.string().min(1) })
const validated = Schema.parse(body)

File Organization

src/
├── app/          # Next.js App Router
├── components/   # React components (PascalCase.tsx)
├── hooks/        # Custom hooks (use*.ts)
├── lib/          # Utilities (camelCase.ts)
├── types/        # TypeScript types (*.types.ts)
└── styles/       # Global styles

Code Smell Detection

• Long Functions: >50 lines → split
• Deep Nesting: >3 levels → early returns
• Magic Numbers: unexplained → named constants

Testing Standards (AAA)

test('returns empty array when no match', () => {
  const result = search(query)
  expect(result).toEqual([])
})

Further Reading

Internal: @.claude/skills/coding-standards/REFERENCE.md - Advanced patterns, hooks library, API design, testing strategies | @.claude/skills/vibe-coding/SKILL.md - Code quality limits

External: TypeScript Handbook | React Docs