Coding Standards & Best Practices

Code Quality Principles

1. Readability First

•Code is read more than written
•Clear variable and function names
•Self-documenting code preferred over comments

2. KISS (Keep It Simple, Stupid)

•Simplest solution that works
•Avoid over-engineering
•Easy to understand > clever code

3. DRY (Don't Repeat Yourself)

•Extract common logic into functions
•Create reusable components

4. YAGNI (You Aren't Gonna Need It)

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

TypeScript/JavaScript Standards

Variable Naming

typescript

// GOOD: Descriptive names
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

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

Function Naming

typescript

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

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

Immutability Pattern (CRITICAL)

typescript

// ALWAYS use spread operator
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// NEVER mutate directly
user.name = 'New Name'  // BAD
items.push(newItem)     // BAD

Error Handling

typescript

// 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/Await Best Practices

typescript

// GOOD: Parallel execution when possible
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// BAD: Sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()
const stats = await fetchStats()

Type Safety

typescript

// GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
}

function getMarket(id: string): Promise<Market> {
  // Implementation
}

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

React Best Practices

Component Structure

typescript

// GOOD: Functional component with types
interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {children}
    </button>
  )
}

Custom Hooks

typescript

// Reusable custom hook
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
}

State Management

typescript

// GOOD: Functional update for state based on previous state
setCount(prev => prev + 1)

// BAD: Direct state reference (can be stale)
setCount(count + 1)

Conditional Rendering

typescript

// GOOD: Clear conditional rendering
{isLoading && <Spinner />}
{error && <ErrorMessage error={error} />}
{data && <DataDisplay data={data} />}

// BAD: Ternary hell
{isLoading ? <Spinner /> : error ? <ErrorMessage /> : data ? <DataDisplay /> : null}

API Design Standards

Response Format

typescript

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

// Success response
return { success: true, data: markets, meta: { total: 100, page: 1, limit: 10 } }

// Error response
return { success: false, error: 'Invalid request' }

Input Validation

typescript

import { z } from 'zod'

const CreateMarketSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().min(1).max(2000),
  endDate: z.string().datetime()
})

const validated = CreateMarketSchema.parse(body)

File Organization

Many Small Files > Few Large Files

•200-400 lines typical
•800 lines maximum
•High cohesion, low coupling
•Single responsibility per file

File Naming

code

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

Code Smell Detection

Long Functions (>50 lines)

typescript

// BAD: Split into smaller functions
function processMarketData() {
  // 100 lines of code
}

// GOOD
function processMarketData() {
  const validated = validateData()
  const transformed = transformData(validated)
  return saveData(transformed)
}

Deep Nesting (>4 levels)

typescript

// BAD: 5+ levels of nesting
if (user) {
  if (user.isAdmin) {
    if (market) {
      // ...
    }
  }
}

// GOOD: Early returns
if (!user) return
if (!user.isAdmin) return
if (!market) return
// Do something

Magic Numbers

typescript

// BAD
if (retryCount > 3) { }

// GOOD
const MAX_RETRIES = 3
if (retryCount > MAX_RETRIES) { }

Checklist

• 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 console.log statements
• No hardcoded values
• No mutation (immutable patterns used)