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

struct-

cond-

couple-

idiom-

data-

pattern-

modern-

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