Coding Standards & Best Practices

--- name: coding-standards description: > Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development. metadata: origin: ECC --- # Coding Standards & Best Practices 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 ``typescript // PASS: GOOD: Descriptive names const marketSearchQuery = 'election' const isUserAuthenticated = true const totalRevenue = 1000 // FAIL: BAD: Unclear names const q = 'election' const flag = true const x = 1000 ` ### Function Naming `typescript // PASS: GOOD: Verb-noun pattern async function fetchMarketData(marketId: string) { } function calculateSimilarity(a: number[], b: number[]) { } function isValidEmail(email: string): boolean { } // FAIL: BAD: Unclear or noun-only async function market(id: string) { } function similarity(a, b) { } function email(e) { } ` ### Immutability Pattern (CRITICAL) `typescript // PASS: ALWAYS use spread operator const updatedUser = { ...user, name: 'New Name' } const updatedArray = [...items, newItem] // FAIL: NEVER mutate directly user.name = 'New Name' // BAD items.push(newItem) // BAD ` ### Error Handling `typescript // PASS: 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') } } // FAIL: BAD: No error handling async function fetchData(url) { const response = await fetch(url) return response.json() } ` ### Async/Await Best Practices `typescript // PASS: GOOD: Parallel execution when possible const [users, markets, stats] = await Promise.all([ fetchUsers(), fetchMarkets(), fetchStats() ]) // FAIL: BAD: Sequential when unnecessary const users = await fetchUsers() const markets = await fetchMarkets() const stats = await fetchStats() ` ### Type Safety `typescript // PASS: GOOD: Proper types interface Market { id: string name: string status: 'active' | 'resolved' | 'closed' created_at: Date } function getMarket(id: string): Promise<Market> { // Implementation } // FAIL: BAD: Using 'any' function getMarket(id: any): Promise<any> { // Implementation } ` ## React Best Practices ### Component Structure `typescript // PASS: 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 ( <button onClick={onClick} disabled={disabled} className={btn btn-${variant}} > {children} </button> ) } // FAIL: BAD: No types, unclear structure export function Button(props) { return <button onClick={props.onClick}>{props.children}</button> } ` ### Custom Hooks `typescript // PASS: GOOD: Reusable custom hook export function useDebounce<T>(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState<T>(value) useEffect(() => { const handler = setTimeout(() => { setDebouncedValue(value) }, delay) return () => clearTimeout(handler) }, [value, delay]) return debouncedValue } // Usage const debouncedQuery = useDebounce(searchQuery, 500) ` ### State Management `typescript // PASS: GOOD: Proper state updates const [count, setCount] = useState(0) // Functional update for state based on previous state setCount(prev => prev + 1) // FAIL: BAD: Direct state reference setCount(count + 1) // Can be stale in async scenarios ` ### Conditional Rendering ``typescript // PASS: GOOD: Clear conditional rendering {isLoading && <Spinner />