clean-code

Clean Code Core Principles

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: clean-code for comprehensive documentation.

Naming

// ❌ Bad
const d = new Date();
const yyyymmdd = formatDate(d);
function calc(a, b) { return a + b; }
const list = users.filter(x => x.active);

// ✅ Good
const currentDate = new Date();
const formattedDate = formatDate(currentDate);
function calculateTotal(price, quantity) { return price * quantity; }
const activeUsers = users.filter(user => user.isActive);

Functions

// ❌ Bad - Too many responsibilities
function processUser(user) {
  validateUser(user);
  saveToDatabase(user);
  sendWelcomeEmail(user);
  updateAnalytics(user);
}

// ✅ Good - Single responsibility
function createUser(userData: UserInput): User {
  const user = validateAndBuildUser(userData);
  return userRepository.save(user);
}

// Separately handle side effects
async function onUserCreated(user: User) {
  await sendWelcomeEmail(user);
  await analytics.trackSignup(user);
}

Early Returns

// ❌ Bad - Nested conditions
function getDiscount(user) {
  if (user) {
    if (user.isPremium) {
      if (user.yearsActive > 2) {
        return 0.2;
      } else {
        return 0.1;
      }
    } else {
      return 0;
    }
  }
  return 0;
}

// ✅ Good - Early returns
function getDiscount(user: User | null): number {
  if (!user) return 0;
  if (!user.isPremium) return 0;
  if (user.yearsActive > 2) return 0.2;
  return 0.1;
}

Avoid Magic Numbers

// ❌ Bad
if (user.age >= 18 && items.length <= 10) { ... }
setTimeout(callback, 86400000);

// ✅ Good
const MINIMUM_AGE = 18;
const MAX_CART_ITEMS = 10;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

if (user.age >= MINIMUM_AGE && items.length <= MAX_CART_ITEMS) { ... }
setTimeout(callback, ONE_DAY_MS);

Principles Summary

Principle	Description
DRY	Don't Repeat Yourself
KISS	Keep It Simple, Stupid
YAGNI	You Aren't Gonna Need It
SRP	Single Responsibility Principle
Composition	Favor composition over inheritance

When NOT to Use This Skill

This skill is focused on code-level quality. Do NOT use for:

• SOLID principles - Use solid-principles skill for OOP design principles
• Git commit quality - Use git-workflow skill for version control best practices
• Performance optimization - Use performance skill for speed/memory optimization
• Security vulnerabilities - Use OWASP or security-specific skills
• Build/tooling configuration - Use framework-specific skills (e.g., biome, vite)

Anti-Patterns

Anti-Pattern	Why It's Bad	Clean Code Solution
God Object	Class with too many responsibilities	Split into focused classes (SRP)
Magic Numbers	Hard to understand context	Use named constants
Deep Nesting	Difficult to follow logic	Early returns, extract functions
Long Parameter Lists	Hard to use and maintain	Parameter objects or builder pattern
Copy-Paste Code	Duplicate bugs, hard to maintain	Extract shared functions (DRY)
Vague Names	data, temp, x	Intention-revealing names
Side Effects in Getters	Unexpected behavior	Pure functions, separate queries from commands
Comments Instead of Code	Outdated comments, cluttered	Self-documenting code with clear names

Quick Troubleshooting

Issue	Check	Solution
Complex function	Cyclomatic complexity > 10	Extract smaller functions, use early returns
Unreadable code	Need comments to explain	Rename variables/functions, extract logic
Duplicated logic	Copy-paste across files	Extract to shared utility/service
Long file	> 300 lines	Split by responsibility, separate concerns
Unclear variable	Name doesn't reveal intent	Rename to describe what it contains/represents
Magic number appearing	Unexplained literal values	Define const with descriptive name

Authoritative Sources

• Clean Code by Robert C. Martin - https://www.oreilly.com/library/view/clean-code-a/9780136083238/
• Refactoring Catalog by Martin Fowler - https://refactoring.com/catalog/

Production Readiness

Code Quality Gates

// eslint.config.js
export default [
  {
    rules: {
      // Complexity limits
      complexity: ['error', { max: 10 }],
      'max-depth': ['error', 4],
      'max-lines-per-function': ['warn', { max: 50 }],
      'max-params': ['warn', { max: 4 }],

      // Maintainability
      'no-duplicate-imports': 'error',
      'no-else-return': 'error',
      'prefer-const': 'error',
      'no-var': 'error',
    },
  },
];

// biome.json
{
  "linter": {
    "rules": {
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": { "maxAllowedComplexity": 15 }
        }
      }
    }
  }
}

Error Handling Patterns

// Custom error hierarchy
class AppError extends Error {
  constructor(
    message: string,
    public code: string,
    public statusCode: number = 500,
    public isOperational: boolean = true
  ) {
    super(message);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 'VALIDATION_ERROR', 400);
  }
}

class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404);
  }
}

// Error boundary pattern
async function handleRequest<T>(operation: () => Promise<T>): Promise<Result<T>> {
  try {
    const data = await operation();
    return { success: true, data };
  } catch (error) {
    if (error instanceof AppError && error.isOperational) {
      return { success: false, error };
    }
    // Log unexpected errors
    logger.error('Unexpected error', { error });
    throw error; // Re-throw for crash recovery
  }
}

Code Review Automation

# .github/workflows/code-quality.yml
name: Code Quality

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: SonarCloud Scan
        uses: SonarSource/sonarcloud-github-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

      - name: Check cognitive complexity
        run: npx @biomejs/biome check --diagnostic-level=error .

      - name: Detect code duplication
        run: npx jscpd src/ --threshold 5

Testing Standards

// Test naming convention
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid data', async () => {
      // Arrange
      const userData = { name: 'John', email: '[email protected]' };

      // Act
      const user = await userService.createUser(userData);

      // Assert
      expect(user.id).toBeDefined();
      expect(user.name).toBe('John');
    });

    it('should throw ValidationError for invalid email', async () => {
      // Arrange
      const invalidData = { name: 'John', email: 'invalid' };

      // Act & Assert
      await expect(userService.createUser(invalidData))
        .rejects.toThrow(ValidationError);
    });
  });
});

// Test coverage thresholds
// vitest.config.ts
{
  test: {
    coverage: {
      provider: 'v8',
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },
  },
}

Documentation Standards

/**
 * Creates a new user in the system.
 *
 * @param data - User creation data
 * @returns The created user with generated ID
 * @throws {ValidationError} If the data is invalid
 * @throws {ConflictError} If email already exists
 *
 * @example
 * ```ts
 * const user = await createUser({
 *   name: 'John Doe',
 *   email: '[email protected]'
 * });
 * ```
 */
async function createUser(data: CreateUserData): Promise<User> {
  // Implementation
}

// README template for modules
/**
 * # User Module
 *
 * ## Overview
 * Handles user management including CRUD operations.
 *
 * ## Usage
 * ```ts
 * import { UserService } from './user';
 * const service = new UserService(repository);
 * ```
 *
 * ## API
 * - `createUser(data)` - Creates a new user
 * - `getUser(id)` - Retrieves user by ID
 * - `updateUser(id, data)` - Updates user data
 */

Monitoring Metrics

Metric	Target
Cognitive complexity	< 15
Cyclomatic complexity	< 10
Code duplication	< 5%
Test coverage	> 80%
Technical debt ratio	< 5%

Checklist

• Meaningful variable/function names
• Single responsibility functions
• Early returns to reduce nesting
• Constants for magic numbers
• Consistent error handling
• Complexity limits in linter
• Test coverage thresholds
• JSDoc for public APIs
• Code duplication detection
• SonarQube quality gate

Reference Documentation

• SOLID Principles
• Design Patterns
• Quality Principles (Consolidated)