Coding Standards

Universal coding standards applicable across all projects.

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

const q = 'election'
const flag = true
const x = 1000

Function Naming

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

async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }

Immutability Pattern (CRITICAL)

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

const updatedArray = [...items, newItem]

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

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 function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}

Async/Await Best Practices

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

// Sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()
const stats = await 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)

// Direct state reference (can be stale)
setCount(count + 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

Long Functions

Bad:

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

Good:

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

Deep Nesting

Bad:

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

Good:

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

// Do something

Magic Numbers

Bad:

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

Good:

const MAX_RETRIES = 3
const DEBOUNCE_DELAY_MS = 500

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

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

Overview

Core Skills

Development Patterns

Language-Specific Skills

Advanced Skills

When to Activate

Code Quality Principles

1. Readability First

2. KISS (Keep It Simple, Stupid)

3. DRY (Don’t Repeat Yourself)

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

TypeScript/JavaScript Standards

Variable Naming

Function Naming

Immutability Pattern (CRITICAL)

Error Handling

Async/Await Best Practices

React Best Practices

Component Structure

State Management

API Design Standards

REST API Conventions

Response Format

Code Smell Detection

​When to Activate

​Code Quality Principles

​1. Readability First

​2. KISS (Keep It Simple, Stupid)

​3. DRY (Don’t Repeat Yourself)

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

​TypeScript/JavaScript Standards

​Variable Naming

​Function Naming

​Immutability Pattern (CRITICAL)

​Error Handling

​Async/Await Best Practices

​React Best Practices

​Component Structure

​State Management

​API Design Standards

​REST API Conventions

​Response Format

​Code Smell Detection

When to Activate

Code Quality Principles

1. Readability First

2. KISS (Keep It Simple, Stupid)

3. DRY (Don’t Repeat Yourself)

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

TypeScript/JavaScript Standards

Variable Naming

Function Naming

Immutability Pattern (CRITICAL)

Error Handling

Async/Await Best Practices

React Best Practices

Component Structure

State Management

API Design Standards

REST API Conventions

Response Format

Code Smell Detection