Coding Standards

Coding Standards

Universal coding standards applicable across all projects. This is the shared foundation that all other skills build upon.

Core Principles

1. Readability First

Code is read more than written. Clear variable names, self-documenting code, consistent formatting.

2. KISS — Keep It Simple

Simplest solution that works. No premature optimization. Easy to understand beats clever.

3. DRY — Don't Repeat Yourself

Extract common logic into functions. Share utilities. Avoid copy-paste.

4. YAGNI — You Aren't Gonna Need It

Don't build features before they're needed. Start simple, refactor when required.

Naming Conventions

Variables

// GOOD: Descriptive names
const searchQuery = 'election'
const isAuthenticated = true
const totalRevenue = 1000

// BAD: Unclear names
const q = 'election'
const flag = true
const x = 1000

Functions

// GOOD: Verb-noun pattern
async function fetchUserData(userId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// BAD: Unclear or noun-only
async function user(id: string) { }
function similarity(a, b) { }

Immutability (CRITICAL)

Always create new objects, never mutate:

// GOOD: Spread operator
const updatedUser = { ...user, name: 'New Name' }
const updatedArray = [...items, newItem]
const withoutItem = items.filter(i => i.id !== removeId)

// BAD: Direct mutation
user.name = 'New Name'
items.push(newItem)

Error Handling

// GOOD: Comprehensive error handling
async function fetchData(url: string) {
  try {
    const response = await fetch(url)
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
    }
    return await response.json()
  } catch (error) {
    console.error('Fetch failed:', error)
    throw new Error('Failed to fetch data')
  }
}

// BAD: No error handling
async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}

Async Best Practices

// GOOD: Parallel execution when independent
const [users, items, stats] = await Promise.all([
  fetchUsers(),
  fetchItems(),
  fetchStats()
])

// BAD: Sequential when unnecessary
const users = await fetchUsers()
const items = await fetchItems()
const stats = await fetchStats()

Type Safety

// GOOD: Proper types
interface User {
  id: string
  name: string
  role: 'admin' | 'user'
  createdAt: Date
}

function getUser(id: string): Promise<User> { }

// BAD: Using 'any'
function getUser(id: any): Promise<any> { }

Input Validation

import { z } from 'zod'

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

const validated = UserSchema.parse(input)

File Organization

Structure

• High cohesion, low coupling
• 200-400 lines typical, 800 max
• Organize by feature/domain, not by type
• Many small files over few large files

Naming

components/Button.tsx          # PascalCase for components
hooks/useAuth.ts              # camelCase with 'use' prefix
lib/formatDate.ts             # camelCase for utilities
types/user.types.ts           # camelCase with .types suffix

Code Smells

Long Functions

// BAD: >50 lines
function processData() { /* 100 lines */ }

// GOOD: Split into focused functions
function processData() {
  const validated = validateData()
  const transformed = transformData(validated)
  return saveData(transformed)
}

Deep Nesting

// BAD: 5+ levels deep
if (user) {
  if (user.isAdmin) {
    if (item) {
      // ...
    }
  }
}

// GOOD: Early returns
if (!user) return
if (!user.isAdmin) return
if (!item) return
// proceed

Magic Numbers

// BAD
if (retryCount > 3) { }
setTimeout(cb, 500)

// GOOD
const MAX_RETRIES = 3
const DEBOUNCE_MS = 500
if (retryCount > MAX_RETRIES) { }
setTimeout(cb, DEBOUNCE_MS)

Comments

// GOOD: Explain WHY, not WHAT
// Use exponential backoff to avoid overwhelming the API during outages
const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)

// BAD: Stating the obvious
// Increment counter by 1
count++

API Response Format

interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
  meta?: {
    total: number
    page: number
    limit: number
  }
}

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 logging sensitive data
• [ ] No hardcoded values
• [ ] Immutable patterns used
• [ ] Types are specific (no any)

Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.