# Coding Standards > Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development. Use when this capability is needed. - Skill: `tomevault-io/coding-standards-17` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/coding-standards-17` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/coding-standards-17/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/coding-standards-17 --- # Coding Standards & Best Practices Universal coding standards applicable across all projects. ## Methodology Integration These standards complement the principles in `.claude/docs/APPROACH.md`: - Small, verifiable steps - Interface-first development - Documentation as memory ## 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) - 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 searchQuery = '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) { } ``` ### 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') } } ``` ### 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 ( ) } ``` ### State Management ```typescript // 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 ``` ## API Design Standards ### REST API Conventions ``` GET /api/resources # List resources GET /api/resources/:id # Get single resource POST /api/resources # Create resource PUT /api/resources/:id # Replace resource PATCH /api/resources/:id # Update resource DELETE /api/resources/:id # Delete resource ``` ### Response Format ```typescript interface ApiResponse { success: boolean data?: T error?: string meta?: { total: number page: number limit: number } } ``` ### Input Validation ```typescript import { z } from 'zod' const CreateResourceSchema = z.object({ name: z.string().min(1).max(200), description: z.string().min(1).max(2000), }) export async function POST(request: Request) { const body = await request.json() try { const validated = CreateResourceSchema.parse(body) // Proceed with validated data } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json({ success: false, error: 'Validation failed', details: error.errors }, { status: 400 }) } } } ``` ## File Organization ### File Naming ``` components/Button.tsx # PascalCase for components hooks/useAuth.ts # camelCase with 'use' prefix lib/formatDate.ts # camelCase for utilities types/market.types.ts # camelCase with .types suffix ``` ## Comments & Documentation ### When to Comment ```typescript // 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) // BAD: Stating the obvious // Increment counter by 1 count++ ``` ## Code Smell Detection Watch for these anti-patterns: ### Long Functions (>50 lines) Split into smaller functions with single responsibilities. ### Deep Nesting (>4 levels) Use early returns to flatten. ### Magic Numbers Use named constants. **Remember**: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/mjnehl) — claim your Tome and manage your conversions.