Coding Standards

​

When to Activate

• Starting a new project or module
• Reviewing code for quality and maintainability
• Refactoring existing code to follow conventions
• Enforcing naming, formatting, or structural consistency
• Setting up linting, formatting, or type-checking rules
• Onboarding new contributors to coding conventions

​

Code Quality Principles

​

1. Readability First

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

​

2. KISS (Keep It Simple, Stupid)

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

​

3. DRY (Don’t Repeat Yourself)

• Extract common logic into functions
• Create reusable components
• Share utilities across modules
• Avoid copy-paste programming

​

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

• Don’t build features before they’re needed
• Avoid speculative generality
• Add complexity only when required
• Start simple, refactor when needed

​

TypeScript/JavaScript Standards

​

Variable Naming

const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

​

Function Naming

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

​

Immutability Pattern (CRITICAL)

const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

​

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')
  }
}

​

Async/Await Best Practices

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

​

React Best Practices

​

Component Structure

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>
  )
}

​

State Management

const [count, setCount] = useState(0)

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

​

API Design Standards

​

REST API Conventions

GET    /api/markets              # List all markets
GET    /api/markets/:id          # Get specific market
POST   /api/markets              # Create new market
PUT    /api/markets/:id          # Update market (full)
PATCH  /api/markets/:id          # Update market (partial)
DELETE /api/markets/:id          # Delete market

# Query parameters for filtering
GET /api/markets?status=active&limit=10&offset=0

​

Response Format

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

// Success response
return NextResponse.json({
  success: true,
  data: markets,
  meta: { total: 100, page: 1, limit: 10 }
})

// Error response
return NextResponse.json({
  success: false,
  error: 'Invalid request'
}, { status: 400 })

​

Code Smell Detection

function processMarketData() {
  // 100 lines of code
}

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

if (user) {
  if (user.isAdmin) {
    if (market) {
      if (market.isActive) {
        if (hasPermission) {
          // Do something
        }
      }
    }
  }
}

if (!user) return
if (!user.isAdmin) return
if (!market) return
if (!market.isActive) return
if (!hasPermission) return

// Do something

if (retryCount > 3) { }
setTimeout(callback, 500)

const MAX_RETRIES = 3
const DEBOUNCE_DELAY_MS = 500

if (retryCount > MAX_RETRIES) { }
setTimeout(callback, DEBOUNCE_DELAY_MS)