coding-standards

name	coding-standards
description	Use when enforcing baseline coding conventions across projects. Covers naming, readability, immutability, and code-quality review. See frontend-patterns or backend-patterns for framework-specific guidance.
origin	MCC

Coding Standards & Best Practices

Baseline coding conventions applicable across projects.

This skill is the shared floor, not the detailed framework playbook.

• Use frontend-patterns for React, state, forms, rendering, and UI architecture.
• Use backend-patterns or api-design for repository/service layers, endpoint design, validation, and server-specific concerns.
• Use rules/common/coding-style.md when you need the shortest reusable rule layer instead of a full skill walkthrough.

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

Scope Boundaries

Activate this skill for:

• descriptive naming
• immutability defaults
• readability, KISS, DRY, and YAGNI enforcement
• error-handling expectations and code-smell review

Do not use this skill as the primary source for:

• React composition, hooks, or rendering patterns
• backend architecture, API design, or database layering
• domain-specific framework guidance when a narrower MCC skill exists

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

3. DRY (Don't Repeat Yourself)

• Extract common logic into functions
• Create reusable components
• Avoid copy-paste programming

4. YAGNI (You Aren't Gonna Need It)

• Don't build features before they're needed
• Start simple, refactor when needed

Naming Conventions

// Variables: descriptive camelCase
const marketSearchQuery = 'election'
const isUserAuthenticated = true

// Functions: verb-noun pattern
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

Immutability Pattern (CRITICAL)

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

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

// 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()

Type Safety

// GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}

// BAD: Using 'any'
function getMarket(id: any): Promise<any> { }

File Organization

src/
├── app/                    # Framework entry
├── components/            # UI components
│   ├── ui/               # Generic UI
│   ├── forms/            # Form components
│   └── layouts/          # Layout components
├── hooks/                # Custom hooks
├── lib/                  # Utilities and configs
├── types/                # TypeScript types
└── styles/              # Global styles

File naming: PascalCase for components, camelCase with use prefix for hooks, camelCase for utilities.

Comments: Explain WHY, Not WHAT

// GOOD: Explain WHY
// 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

Long Functions

Split functions over 50 lines into smaller focused pieces.

Deep Nesting

Use early returns instead of 5+ levels of nesting.

Magic Numbers

Use named constants: const MAX_RETRIES = 3 not if (retryCount > 3).

Reference Files

• react-and-api-examples.md — React component structure, custom hooks, state management, conditional rendering, REST API conventions, response format, input validation with Zod
• performance-and-testing-examples.md — memoization, lazy loading, database queries, AAA test pattern, test naming, JSDoc for public APIs

Remember: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.