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

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