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