--- name: coding-standards description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development. user-invocable: false context: fork agent: Explore --- # Coding Standards & Best Practices Universal coding standards applicable across all projects. ## 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 ```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) { } function email(e) { } ``` ### 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' created_at: Date } function getMarket(id: string): Promise { \/\/ Implementation } \/\/ ❌ BAD: Using 'any' function getMarket(id: any): Promise { \/\/ 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 (