Coding Standards

1---
2name: coding-standards
3description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.
4author: affaan-m
5version: "1.0"
6---
7 
8# Coding Standards & Best Practices
9 
10Universal coding standards applicable across all projects.
11 
12## Code Quality Principles
13 
14### 1. Readability First
15- Code is read more than written
16- Clear variable and function names
17- Self-documenting code preferred over comments
18- Consistent formatting
19 
20### 2. KISS (Keep It Simple, Stupid)
21- Simplest solution that works
22- Avoid over-engineering
23- No premature optimization
24- Easy to understand > clever code
25 
26### 3. DRY (Don't Repeat Yourself)
27- Extract common logic into functions
28- Create reusable components
29- Share utilities across modules
30- Avoid copy-paste programming
31 
32### 4. YAGNI (You Aren't Gonna Need It)
33- Don't build features before they're needed
34- Avoid speculative generality
35- Add complexity only when required
36- Start simple, refactor when needed
37 
38## TypeScript/JavaScript Standards
39 
40### Variable Naming
41 
42```typescript
43// ✅ GOOD: Descriptive names
44const marketSearchQuery = 'election'
45const isUserAuthenticated = true
46const totalRevenue = 1000
47 
48// ❌ BAD: Unclear names
49const q = 'election'
50const flag = true
51const x = 1000
52```
53 
54### Function Naming
55 
56```typescript
57// ✅ GOOD: Verb-noun pattern
58async function fetchMarketData(marketId: string) { }
59function calculateSimilarity(a: number[], b: number[]) { }
60function isValidEmail(email: string): boolean { }
61 
62// ❌ BAD: Unclear or noun-only
63async function market(id: string) { }
64function similarity(a, b) { }
65function email(e) { }
66```
67 
68### Immutability Pattern (CRITICAL)
69 
70```typescript
71// ✅ ALWAYS use spread operator
72const updatedUser = {
73  ...user,
74  name: 'New Name'
75}
76 
77const updatedArray = [...items, newItem]
78 
79// ❌ NEVER mutate directly
80user.name = 'New Name'  // BAD
81items.push(newItem)     // BAD
82```
83 
84### Error Handling
85 
86```typescript
87// ✅ GOOD: Comprehensive error handling
88async function fetchData(url: string) {
89  try {
90    const response = await fetch(url)
91 
92    if (!response.ok) {
93      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
94    }
95 
96    return await response.json()
97  } catch (error) {
98    console.error('Fetch failed:', error)
99    throw new Error('Failed to fetch data')
100  }
101}
102 
103// ❌ BAD: No error handling
104async function fetchData(url) {
105  const response = await fetch(url)
106  return response.json()
107}
108```
109 
110### Async/Await Best Practices
111 
112```typescript
113// ✅ GOOD: Parallel execution when possible
114const [users, markets, stats] = await Promise.all([
115  fetchUsers(),
116  fetchMarkets(),
117  fetchStats()
118])
119 
120// ❌ BAD: Sequential when unnecessary
121const users = await fetchUsers()
122const markets = await fetchMarkets()
123const stats = await fetchStats()
124```
125 
126### Type Safety
127 
128```typescript
129// ✅ GOOD: Proper types
130interface Market {
131  id: string
132  name: string
133  status: 'active' | 'resolved' | 'closed'
134  created_at: Date
135}
136 
137function getMarket(id: string): Promise<Market> {
138  // Implementation
139}
140 
141// ❌ BAD: Using 'any'
142function getMarket(id: any): Promise<any> {
143  // Implementation
144}
145```
146 
147## React Best Practices
148 
149### Component Structure
150 
151```typescript
152// ✅ GOOD: Functional component with types
153interface ButtonProps {
154  children: React.ReactNode
155  onClick: () => void
156  disabled?: boolean
157  variant?: 'primary' | 'secondary'
158}
159 
160export function Button({
161  children,
162  onClick,
163  disabled = false,
164  variant = 'primary'
165}: ButtonProps) {
166  return (
167    <button
168      onClick={onClick}
169      disabled={disabled}
170      className={`btn btn-${variant}`}
171    >
172      {children}
173    </button>
174  )
175}
176 
177// ❌ BAD: No types, unclear structure
178export function Button(props) {
179  return <button onClick={props.onClick}>{props.children}</button>
180}
181```
182 
183### Custom Hooks
184 
185```typescript
186// ✅ GOOD: Reusable custom hook
187export function useDebounce<T>(value: T, delay: number): T {
188  const [debouncedValue, setDebouncedValue] = useState<T>(value)
189 
190  useEffect(() => {
191    const handler = setTimeout(() => {
192      setDebouncedValue(value)
193    }, delay)
194 
195    return () => clearTimeout(handler)
196  }, [value, delay])
197 
198  return debouncedValue
199}
200 
201// Usage
202const debouncedQuery = useDebounce(searchQuery, 500)
203```
204 
205### State Management
206 
207```typescript
208// ✅ GOOD: Proper state updates
209const [count, setCount] = useState(0)
210 
211// Functional update for state based on previous state
212setCount(prev => prev + 1)
213 
214// ❌ BAD: Direct state reference
215setCount(count + 1)  // Can be stale in async scenarios
216```
217 
218### Conditional Rendering
219 
220```typescript
221// ✅ GOOD: Clear conditional rendering
222{isLoading && <Spinner />}
223{error && <ErrorMessage error={error} />}
224{data && <DataDisplay data={data} />}
225 
226// ❌ BAD: Ternary hell
227{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}
228```
229 
230## API Design Standards
231 
232### REST API Conventions
233 
234```
235GET    /api/markets              # List all markets
236GET    /api/markets/:id          # Get specific market
237POST   /api/markets              # Create new market
238PUT    /api/markets/:id          # Update market (full)
239PATCH  /api/markets/:id          # Update market (partial)
240DELETE /api/markets/:id          # Delete market
241 
242# Query parameters for filtering
243GET /api/markets?status=active&limit=10&offset=0
244```
245 
246### Response Format
247 
248```typescript
249// ✅ GOOD: Consistent response structure
250interface ApiResponse<T> {
251  success: boolean
252  data?: T
253  error?: string
254  meta?: {
255    total: number
256    page: number
257    limit: number
258  }
259}
260 
261// Success response
262return NextResponse.json({
263  success: true,
264  data: markets,
265  meta: { total: 100, page: 1, limit: 10 }
266})
267 
268// Error response
269return NextResponse.json({
270  success: false,
271  error: 'Invalid request'
272}, { status: 400 })
273```
274 
275### Input Validation
276 
277```typescript
278import { z } from 'zod'
279 
280// ✅ GOOD: Schema validation
281const CreateMarketSchema = z.object({
282  name: z.string().min(1).max(200),
283  description: z.string().min(1).max(2000),
284  endDate: z.string().datetime(),
285  categories: z.array(z.string()).min(1)
286})
287 
288export async function POST(request: Request) {
289  const body = await request.json()
290 
291  try {
292    const validated = CreateMarketSchema.parse(body)
293    // Proceed with validated data
294  } catch (error) {
295    if (error instanceof z.ZodError) {
296      return NextResponse.json({
297        success: false,
298        error: 'Validation failed',
299        details: error.errors
300      }, { status: 400 })
301    }
302  }
303}
304```
305 
306## File Organization
307 
308### Project Structure
309 
310```
311src/
312├── app/                    # Next.js App Router
313│   ├── api/               # API routes
314│   ├── markets/           # Market pages
315│   └── (auth)/           # Auth pages (route groups)
316├── components/            # React components
317│   ├── ui/               # Generic UI components
318│   ├── forms/            # Form components
319│   └── layouts/          # Layout components
320├── hooks/                # Custom React hooks
321├── lib/                  # Utilities and configs
322│   ├── api/             # API clients
323│   ├── utils/           # Helper functions
324│   └── constants/       # Constants
325├── types/                # TypeScript types
326└── styles/              # Global styles
327```
328 
329### File Naming
330 
331```
332components/Button.tsx          # PascalCase for components
333hooks/useAuth.ts              # camelCase with 'use' prefix
334lib/formatDate.ts             # camelCase for utilities
335types/market.types.ts         # camelCase with .types suffix
336```
337 
338## Comments & Documentation
339 
340### When to Comment
341 
342```typescript
343// ✅ GOOD: Explain WHY, not WHAT
344// Use exponential backoff to avoid overwhelming the API during outages
345const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)
346 
347// Deliberately using mutation here for performance with large arrays
348items.push(newItem)
349 
350// ❌ BAD: Stating the obvious
351// Increment counter by 1
352count++
353 
354// Set name to user's name
355name = user.name
356```
357 
358### JSDoc for Public APIs
359 
360```typescript
361/**
362 * Searches markets using semantic similarity.
363 *
364 * @param query - Natural language search query
365 * @param limit - Maximum number of results (default: 10)
366 * @returns Array of markets sorted by similarity score
367 * @throws {Error} If OpenAI API fails or Redis unavailable
368 *
369 * @example
370 * ```typescript
371 * const results = await searchMarkets('election', 5)
372 * console.log(results[0].name) // "Trump vs Biden"
373 * ```
374 */
375export async function searchMarkets(
376  query: string,
377  limit: number = 10
378): Promise<Market[]> {
379  // Implementation
380}
381```
382 
383## Performance Best Practices
384 
385### Memoization
386 
387```typescript
388import { useMemo, useCallback } from 'react'
389 
390// ✅ GOOD: Memoize expensive computations
391const sortedMarkets = useMemo(() => {
392  return markets.sort((a, b) => b.volume - a.volume)
393}, [markets])
394 
395// ✅ GOOD: Memoize callbacks
396const handleSearch = useCallback((query: string) => {
397  setSearchQuery(query)
398}, [])
399```
400 
401### Lazy Loading
402 
403```typescript
404import { lazy, Suspense } from 'react'
405 
406// ✅ GOOD: Lazy load heavy components
407const HeavyChart = lazy(() => import('./HeavyChart'))
408 
409export function Dashboard() {
410  return (
411    <Suspense fallback={<Spinner />}>
412      <HeavyChart />
413    </Suspense>
414  )
415}
416```
417 
418### Database Queries
419 
420```typescript
421// ✅ GOOD: Select only needed columns
422const { data } = await supabase
423  .from('markets')
424  .select('id, name, status')
425  .limit(10)
426 
427// ❌ BAD: Select everything
428const { data } = await supabase
429  .from('markets')
430  .select('*')
431```
432 
433## Testing Standards
434 
435### Test Structure (AAA Pattern)
436 
437```typescript
438test('calculates similarity correctly', () => {
439  // Arrange
440  const vector1 = [1, 0, 0]
441  const vector2 = [0, 1, 0]
442 
443  // Act
444  const similarity = calculateCosineSimilarity(vector1, vector2)
445 
446  // Assert
447  expect(similarity).toBe(0)
448})
449```
450 
451### Test Naming
452 
453```typescript
454// ✅ GOOD: Descriptive test names
455test('returns empty array when no markets match query', () => { })
456test('throws error when OpenAI API key is missing', () => { })
457test('falls back to substring search when Redis unavailable', () => { })
458 
459// ❌ BAD: Vague test names
460test('works', () => { })
461test('test search', () => { })
462```
463 
464## Code Smell Detection
465 
466Watch for these anti-patterns:
467 
468### 1. Long Functions
469```typescript
470// ❌ BAD: Function > 50 lines
471function processMarketData() {
472  // 100 lines of code
473}
474 
475// ✅ GOOD: Split into smaller functions
476function processMarketData() {
477  const validated = validateData()
478  const transformed = transformData(validated)
479  return saveData(transformed)
480}
481```
482 
483### 2. Deep Nesting
484```typescript
485// ❌ BAD: 5+ levels of nesting
486if (user) {
487  if (user.isAdmin) {
488    if (market) {
489      if (market.isActive) {
490        if (hasPermission) {
491          // Do something
492        }
493      }
494    }
495  }
496}
497 
498// ✅ GOOD: Early returns
499if (!user) return
500if (!user.isAdmin) return
501if (!market) return
502if (!market.isActive) return
503if (!hasPermission) return
504 
505// Do something
506```
507 
508### 3. Magic Numbers
509```typescript
510// ❌ BAD: Unexplained numbers
511if (retryCount > 3) { }
512setTimeout(callback, 500)
513 
514// ✅ GOOD: Named constants
515const MAX_RETRIES = 3
516const DEBOUNCE_DELAY_MS = 500
517 
518if (retryCount > MAX_RETRIES) { }
519setTimeout(callback, DEBOUNCE_DELAY_MS)
520```
521 
522**Remember**: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.