coding-standards

// ✅ GOOD: Descriptive names
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000
 
// ❌ BAD: Unclear names
const q = 'election'
const flag = true
const x = 1000

// ✅ 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

// ✅ 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

// ✅ 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

// ✅ 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

// ✅ GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}
 
function getMarket(id: string): Promise<Market> {

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

// ✅ GOOD: Reusable custom hook
export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)
 
  useEffect(() => {

// ✅ GOOD: Proper state updates
const [count, setCount] = useState(0)
 
// Functional update for state based on previous state
setCount(prev => prev + 1)
 
// ❌ BAD: Direct state reference
setCount(count + 1)  // Can be stale in async scenarios

// ✅ GOOD: Clear conditional rendering
{isLoading && <Spinner />}
{error && <ErrorMessage error={error} />}
{data && <DataDisplay data={data} />}
 
// ❌ BAD: Ternary hell
{isLoading ? <Spinner /> : error ? <ErrorMessage error

// ✅ GOOD: Consistent response structure
interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
  meta?: {
    total: number
    page: number
    limit: number
  }
}
 
// Success response

import { z } from 'zod'
 
// ✅ GOOD: Schema validation
const CreateMarketSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().min(1).max

// ✅ 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)
 
// Deliberately using mutation here for performance with large arrays
items.push(newItem)
 
// ❌ BAD: Stating the obvious
// Increment counter by 1
count++
 
// Set name to user's name
name =

/**
 * Searches markets using semantic similarity.
 *
 * @param query - Natural language search query
 * @param limit - Maximum number of results (default: 10)
 * @returns Array of markets sorted by similarity score
 * @throws {Error} If OpenAI API fails or Redis unavailable
 *
 * @example
 * ```typescript
 * const results = await searchMarkets('election', 5)
 * console.log(results[0].name) // "Trump vs Biden"

import { useMemo, useCallback } from 'react'
 
// ✅ GOOD: Memoize expensive computations
const sortedMarkets = useMemo(() => {
  return markets.sort((a, b) => b.volume - a.volume)
}, [markets])
 
// ✅ GOOD: Memoize callbacks
const handleSearch = useCallback((query

import { lazy, Suspense } from 'react'
 
// ✅ GOOD: Lazy load heavy components
const HeavyChart = lazy(() => import('./HeavyChart'))
 
export function Dashboard() {
  return (
    <Suspense fallback={<Spinner />}>
      <HeavyChart />
    </Suspense>
  )

// ✅ GOOD: Select only needed columns
const { data } = await supabase
  .from('markets')
  .select('id, name, status')
  .limit(10)
 
// ❌ BAD: Select everything
const { data } = await supabase
  .from('markets'

test('calculates similarity correctly', () => {
  // Arrange
  const vector1 = [1, 0, 0]
  const vector2 = [0, 1, 0]
 
  // Act
  const similarity = calculateCosineSimilarity(vector1, vector2)
 
  // Assert

// ✅ GOOD: Descriptive test names
test('returns empty array when no markets match query', () => { })
test('throws error when OpenAI API key is missing', () => { })
test('falls back to substring search when Redis unavailable', () => { })
 
// ❌ BAD: Vague test names
test('works', () => { })
test('test search', () => { })

// ❌ BAD: Function > 50 lines
function processMarketData() {
  // 100 lines of code
}
 
// ✅ GOOD: Split into smaller functions
function processMarketData() {
  const validated = validateData()
  const transformed = transformData(validated)
  return saveData(transformed)
}

// ❌ BAD: 5+ levels of nesting
if (user) {
  if (user.isAdmin) {
    if (market) {
      if (market.isActive) {
        if (hasPermission) {
          // Do something
        }
      }
    }
  }
}
 
// ✅ GOOD: Early returns
if (!user) return
if (!user.isAdmin) return

// ❌ BAD: Unexplained numbers
if (retryCount > 3) { }
setTimeout(callback, 500)
 
// ✅ GOOD: Named constants
const MAX_RETRIES = 3
const DEBOUNCE_DELAY_MS = 500
 
if (retryCount > MAX_RETRIES) { }
setTimeout(callback, DEBOUNCE_DELAY_MS)