ruby-refactor

Community Ruby Refactoring Best Practices

Comprehensive refactoring guide for Ruby applications, maintained by the community. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Refactoring Ruby code to reduce complexity and improve design
• Extracting methods, classes, or value objects from large units
• Simplifying complex conditionals and deep nesting
• Reducing coupling between classes and modules
• Adopting idiomatic Ruby patterns and modern Ruby 3.x features

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Structure & Decomposition	CRITICAL	struct-
2	Conditional Simplification	CRITICAL	cond-
3	Coupling & Dependencies	HIGH	couple-
4	Ruby Idioms	HIGH	idiom-
5	Data & Value Objects	MEDIUM-HIGH	data-
6	Design Patterns	MEDIUM	pattern-
7	Modern Ruby 3.x	MEDIUM	modern-
8	Naming & Readability	LOW-MEDIUM	name-

Quick Reference

1. Structure & Decomposition (CRITICAL)

• struct-extract-method - Extract Long Methods into Focused Units
• struct-extract-class - Extract Class for Single Responsibility
• struct-parameter-object - Introduce Parameter Object for Long Signatures
• struct-compose-method - Compose Methods at Single Abstraction Level
• struct-replace-method-with-object - Replace Complex Method with Method Object
• struct-single-responsibility - One Reason to Change per Class
• struct-flatten-deep-nesting - Flatten Deep Nesting with Early Extraction

2. Conditional Simplification (CRITICAL)

• cond-guard-clauses - Replace Nested Conditionals with Guard Clauses
• cond-decompose-conditional - Extract Complex Booleans into Named Predicates
• cond-replace-with-polymorphism - Replace case/when with Polymorphism
• cond-null-object - Replace nil Checks with Null Object
• cond-pattern-matching - Use Pattern Matching for Structural Conditions
• cond-consolidate-duplicates - Consolidate Duplicate Conditional Fragments

3. Coupling & Dependencies (HIGH)

• couple-law-of-demeter - Enforce Law of Demeter with Delegation
• couple-feature-envy - Move Method to Resolve Feature Envy
• couple-dependency-injection - Inject Dependencies via Constructor Defaults
• couple-composition-over-inheritance - Replace Mixin with Composed Object
• couple-tell-dont-ask - Tell Objects What to Do, Don't Query Their State
• couple-avoid-class-methods-domain - Avoid Class Methods in Domain Logic

4. Ruby Idioms (HIGH)

• idiom-prefer-enumerable - Use map/select/reject Over each with Accumulator
• idiom-keyword-arguments - Use Keyword Arguments for Clarity
• idiom-duck-typing - Use respond_to? Over is_a? for Type Checking
• idiom-predicate-methods - Name Boolean Methods with ? Suffix
• idiom-respond-to-missing - Always Pair method_missing with respond_to_missing?
• idiom-block-yield - Use yield Over block.call for Simple Blocks
• idiom-implicit-return - Omit Explicit return for Last Expression

5. Data & Value Objects (MEDIUM-HIGH)

• data-value-object - Replace Primitive Obsession with Value Objects
• data-define-immutable - Use Data.define for Immutable Value Objects
• data-encapsulate-collection - Encapsulate Collections Behind Domain Methods
• data-replace-data-clump - Replace Data Clumps with Grouped Objects
• data-separate-query-command - Separate Query Methods from Command Methods

6. Design Patterns (MEDIUM)

• pattern-strategy - Extract Algorithm Variations into Strategy Objects
• pattern-factory - Use Factory Method to Abstract Object Creation
• pattern-template-method - Define Algorithm Skeleton with Template Method
• pattern-decorator - Wrap Objects with Decorator for Added Behavior
• pattern-null-object-protocol - Implement Null Object with Full Protocol

7. Modern Ruby 3.x (MEDIUM)

• modern-pattern-matching - Use case/in for Structural Pattern Matching
• modern-deconstruct-keys - Implement deconstruct_keys for Custom Pattern Matching
• modern-endless-methods - Use Endless Method Definition for Simple Methods
• modern-hash-pattern-guard - Use Pattern Matching with Guard Clauses
• modern-rightward-assignment - Use Rightward Assignment for Pipeline Expressions

8. Naming & Readability (LOW-MEDIUM)

• name-intention-revealing - Use Intention-Revealing Names
• name-consistent-vocabulary - Use One Word per Concept Across Codebase
• name-avoid-abbreviations - Spell Out Names Except Universal Abbreviations
• name-rename-to-remove-comments - Rename to Eliminate Need for Comments

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

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information