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