/clean-code-principles

Clean Code Principles - Rule Categories

This document defines the organizational structure for clean code principles, ordered by priority and impact.

Category Overview

1. SOLID Principles (CRITICAL)

Priority: CRITICAL Impact: Architectural foundation, affects entire codebase structure Prefix: solid-

The five fundamental principles of object-oriented design that guide maintainable, scalable software architecture.

Rules

Single Responsibility Principle (SRP)

• solid-srp-class - A class should have only one reason to change
• solid-srp-function - A function should do one thing and do it well

Open/Closed Principle (OCP)

• solid-ocp-extension - Open for extension, closed for modification
• solid-ocp-abstraction - Use abstractions to enable extension

Liskov Substitution Principle (LSP)

• solid-lsp-contracts - Subtypes must honor base type contracts
• solid-lsp-preconditions - Cannot strengthen preconditions or weaken postconditions

Interface Segregation Principle (ISP)

• solid-isp-clients - Client-specific interfaces, not general-purpose
• solid-isp-interfaces - Small, cohesive interfaces

Dependency Inversion Principle (DIP)

• solid-dip-abstractions - Depend on abstractions, not concretions
• solid-dip-injection - Inject dependencies from outside

Key Concepts:

• Architectural soundness
• Maintainability at scale
• Testability through design
• Flexibility for change
• Reduced coupling

When to Apply:

• Designing new features or systems
• Refactoring existing architecture
• Addressing technical debt
• Improving testability
• Planning for future extensibility

2. Core Principles (CRITICAL)

Priority: CRITICAL Impact: Daily coding practices, code quality foundation Prefix: core-

Fundamental principles that apply to every line of code you write, regardless of paradigm or language.

Rules

DRY (Don't Repeat Yourself)

• core-dry - Every piece of knowledge should have a single representation
• core-dry-extraction - Extract duplicated code into reusable functions
• core-dry-single-source - Single source of truth for configuration and data

KISS (Keep It Simple, Stupid)

• core-kiss-simplicity - Choose the simplest solution that works
• core-kiss-readability - Optimize for readability over cleverness

YAGNI (You Aren't Gonna Need It)

• core-yagni-features - Don't implement features before they're needed
• core-yagni-abstractions - Don't create abstractions prematurely

Other Core Principles

• core-separation-concerns - Different concerns in different modules
• core-composition - Favor composition over inheritance
• core-law-demeter - Only talk to immediate friends
• core-fail-fast - Detect and report errors early
• core-encapsulation - Hide implementation details

Key Concepts:

• Code duplication elimination
• Simplicity over complexity
• Lean development
• Modularity
• Information hiding

When to Apply:

• Writing any new code
• Code reviews
• Refactoring sessions
• Bug fixes
• Performance optimization

3. Design Patterns (HIGH)

Priority: HIGH Impact: Solves recurring problems with proven solutions Prefix: pattern-

Common design patterns that provide tested solutions to recurring software design problems.

Rules

• pattern-repository - Abstraction for data access layer
• pattern-factory - Object creation without specifying exact class (planned)
• pattern-strategy - Encapsulate algorithms for runtime selection (planned)
• pattern-decorator - Add behavior without modifying objects (planned)
• pattern-observer - Define one-to-many dependencies (planned)
• pattern-adapter - Make incompatible interfaces work together (planned)
• pattern-facade - Simplified interface to complex subsystems (planned)

Key Concepts:

• Proven solutions
• Common vocabulary
• Design reusability
• Best practices codified
• Language-agnostic approaches

When to Apply:

• Solving common architectural problems
• Improving code structure
• Reducing coupling between components
• Making systems more testable
• Communicating design intent

4. Code Organization (HIGH)

Priority: HIGH Impact: Project structure, module boundaries, discoverability Prefix: org-

Principles for organizing code into modules, packages, and directories for maintainability and scalability.

Rules (Planned)

• org-feature-folders - Organize by feature, not by layer
• org-module-boundaries - Clear boundaries between modules
• org-layered-architecture - Proper separation of layers
• org-package-cohesion - Keep related code together
• org-circular-dependencies - Avoid circular imports

Key Concepts:

• Feature-based organization
• Module boundaries
• Layer separation
• Dependency direction
• Discoverability

When to Apply:

• Starting new projects
• Restructuring existing codebases
• Scaling applications
• Onboarding new team members
• Managing microservices

5. Naming & Readability (MEDIUM)

Priority: MEDIUM Impact: Code comprehension, maintenance speed Prefix: name-

Conventions and principles for naming variables, functions, classes, and other identifiers.

Rules (Planned)

• name-meaningful - Use intention-revealing names
• name-consistent - Follow consistent naming conventions
• name-searchable - Avoid magic numbers and strings
• name-avoid-encodings - No Hungarian notation
• name-domain-language - Use ubiquitous domain language

Key Concepts:

• Intention revelation
• Consistency
• Searchability
• Domain terminology
• Avoid abbreviations

When to Apply:

• Creating new identifiers
• Refactoring unclear names
• Code reviews
• Domain modeling
• API design

6. Functions & Methods (MEDIUM)

Priority: MEDIUM Impact: Code readability, testability at function level Prefix: func-

Principles for writing clean, focused functions and methods.

Rules (Planned)

• func-small - Keep functions small and focused
• func-single-purpose - Do one thing only
• func-few-arguments - Limit function parameters
• func-no-side-effects - Minimize or document side effects
• func-command-query - Separate commands from queries

Key Concepts:

• Small functions
• Single purpose
• Few parameters
• Pure functions when possible
• Predictable behavior

When to Apply:

• Writing new functions
• Refactoring long methods
• Improving testability
• Code reviews
• Performance optimization

7. Comments & Documentation (LOW)

Priority: LOW Impact: Code maintainability, knowledge transfer Prefix: doc-

Guidelines for when and how to use comments and documentation effectively.

Rules (Planned)

• doc-self-documenting - Write code that explains itself
• doc-why-not-what - Comments should explain why, not what
• doc-avoid-noise - No redundant or obvious comments
• doc-api-docs - Document public APIs and interfaces

Key Concepts:

• Self-documenting code
• Intent over implementation
• Avoid redundancy
• Public API documentation
• Living documentation

When to Apply:

• Complex business logic
• Non-obvious algorithms
• Public APIs
• Architectural decisions
• Workarounds and hacks

Rule Naming Convention

All rules follow a consistent naming pattern:

{prefix}-{concept}-{specificity}

Examples:

• solid-srp-class - SOLID principle, SRP concept, class level
• core-dry-extraction - Core principle, DRY concept, extraction technique
• pattern-repository - Design pattern category, repository pattern

Priority Levels Explained

• CRITICAL: Core architectural and coding principles. Violations significantly impact maintainability, testability, and scalability.
• HIGH: Important patterns and organizational principles. Violations complicate future development.
• MEDIUM: Best practices that improve code quality. Violations make code harder to read and maintain.
• LOW: Nice-to-have practices. Violations have minimal impact but reduce clarity.

Impact Assessment

• CRITICAL Impact: Affects entire system architecture, multiple teams, long-term maintainability
• HIGH Impact: Affects module design, team productivity, medium-term maintainability
• MEDIUM Impact: Affects code readability, individual developer productivity
• LOW Impact: Affects code clarity, documentation quality

Usage Guidelines

1. Start with SOLID and Core Principles - these are non-negotiable
2. Apply Design Patterns when solving specific architectural problems
3. Use Code Organization principles when structuring projects
4. Follow Naming & Readability guidelines for all new code
5. Apply Function principles during refactoring and new development
6. Add Comments only when necessary to explain complex logic

Cross-References

Rules often relate to each other. The related field in each rule's frontmatter indicates:

• Rules that commonly apply together
• Rules that solve similar problems
• Rules that complement each other
• Rules that provide context or prerequisites

Evolution

This categorization will evolve as:

• New rules are added
• Patterns emerge from practice
• Team feedback is incorporated
• Language-specific adaptations are needed