clean-code

Clean Code Standards

Summary

Establishes consistent code quality standards and best practices for maintainable, readable code across the project.

Context

Clean code reduces technical debt, improves team collaboration, and makes the codebase more maintainable over time. These standards ensure consistency regardless of who is writing the code.

Instructions

General Principles

• Clarity over cleverness - Write code that tells a story
• Consistency - Follow established patterns throughout the codebase
• Simplicity - Prefer simple solutions over complex ones
• Single Responsibility - Each function/class should have one clear purpose

Naming Conventions

• Variables: Use descriptive, meaningful names

  • Good: userAuthenticationToken, isEmailValid
  • Bad: token, flag, data

• Functions: Use verb-noun combinations that describe what the function does

  • Good: validateUserEmail(), fetchUserProfile()
  • Bad: check(), handle(), process()

• Constants: Use UPPER_SNAKE_CASE for constants

  • Good: MAX_RETRY_ATTEMPTS, API_BASE_URL
  • Bad: maxRetries, apiUrl

Function Guidelines

• Keep functions small - Aim for 20 lines or fewer
• Single responsibility - One function, one job
• Pure functions when possible - Predictable inputs and outputs
• Avoid deep nesting - Use early returns to reduce complexity

Code Organization

• Group related functionality together
• Separate concerns - Business logic, UI logic, data access
• Use consistent file structure across similar components
• Import organization - External libraries, internal modules, relative imports

Comments and Documentation

• Write self-documenting code - Good names reduce need for comments
• Comment the "why", not the "what" - Explain business logic and decisions
• Keep comments up to date - Outdated comments are worse than no comments
• Use JSDoc/TSDoc for public APIs and complex functions