Fowler/Martin Code Refactoring Best Practices

Comprehensive code refactoring guide based on Martin Fowler's catalog and Clean Code principles, designed for AI agents and LLMs. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• •Refactoring existing code to improve maintainability
• •Decomposing long methods or large classes
• •Reducing coupling between components
• •Simplifying complex conditional logic
• •Reviewing code for code smells and anti-patterns

Rule Categories by Priority

Quick Reference

1. Structure & Decomposition (CRITICAL)

• •struct-extract-method - Extract Method for Long Functions
• •struct-single-responsibility - Apply Single Responsibility Principle
• •struct-extract-class - Extract Class from Large Class
• •struct-compose-method - Compose Method for Readable Flow
• •struct-function-length - Keep Functions Under 20 Lines
• •struct-replace-method-with-object - Replace Method with Method Object
• •struct-parameter-object - Introduce Parameter Object

2. Coupling & Dependencies (CRITICAL)

• •couple-dependency-injection - Use Dependency Injection
• •couple-hide-delegate - Hide Delegate to Reduce Coupling
• •couple-remove-middle-man - Remove Middle Man When Excessive
• •couple-feature-envy - Fix Feature Envy by Moving Methods
• •couple-interface-segregation - Apply Interface Segregation Principle
• •couple-preserve-whole-object - Preserve Whole Object Instead of Fields

3. Naming & Clarity (HIGH)

• •name-intention-revealing - Use Intention-Revealing Names
• •name-avoid-abbreviations - Avoid Abbreviations and Acronyms
• •name-consistent-vocabulary - Use Consistent Vocabulary
• •name-searchable-names - Use Searchable Names
• •name-avoid-encodings - Avoid Type Encodings in Names

4. Conditional Logic (HIGH)

• •cond-guard-clauses - Replace Nested Conditionals with Guard Clauses
• •cond-polymorphism - Replace Conditional with Polymorphism
• •cond-decompose - Decompose Complex Conditionals
• •cond-consolidate - Consolidate Duplicate Conditional Fragments
• •cond-special-case - Introduce Special Case Object
• •cond-lookup-table - Replace Conditional with Lookup Table

5. Abstraction & Patterns (MEDIUM-HIGH)

• •pattern-strategy - Extract Strategy for Algorithm Variants
• •pattern-template-method - Use Template Method for Shared Skeleton
• •pattern-factory - Use Factory for Complex Object Creation
• •pattern-open-closed - Apply Open-Closed Principle
• •pattern-composition-over-inheritance - Prefer Composition Over Inheritance
• •pattern-extract-superclass - Extract Superclass for Common Behavior

6. Data Organization (MEDIUM)

• •data-encapsulate-collection - Encapsulate Collection
• •data-replace-primitive - Replace Primitive with Object
• •data-encapsulate-record - Encapsulate Record into Class
• •data-split-variable - Split Variable with Multiple Assignments
• •data-replace-temp-with-query - Replace Temp with Query

7. Error Handling (MEDIUM)

• •error-exceptions-over-codes - Use Exceptions Instead of Error Codes
• •error-custom-exceptions - Create Domain-Specific Exception Types
• •error-fail-fast - Fail Fast with Preconditions
• •error-separate-concerns - Separate Error Handling from Business Logic

8. Micro-Refactoring (LOW)

• •micro-remove-dead-code - Remove Dead Code
• •micro-inline-variable - Inline Trivial Variables
• •micro-simplify-expressions - Simplify Boolean Expressions
• •micro-rename-for-clarity - Rename for Clarity

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules
• •Individual rules: references/{prefix}-{slug}.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md