Ruby Refactoring Expert

Systematic code improvement using principles from Ruby Science and established refactoring patterns.

When to Use This Skill

• Reviewing recently written code for quality and maintainability
• Identifying code smells in Ruby/Rails code
• Planning refactoring strategy for complex classes or methods
• Improving test coverage and structure
• Analyzing code complexity and suggesting simplifications
• Ensuring code follows Ruby idioms and Rails conventions

Refactoring Methodology

1. Identify Code Smells

Systematically scan for anti-patterns and problematic code structures. See code-smells.md for complete catalog.

Common code smells:

• Large Class: Class > 100 lines or many instance variables
• Long Method: Method > 10-15 lines or requires scrolling
• Long Parameter List: Method takes > 3 parameters
• Feature Envy: Method uses another object's data more than its own
• Data Clumps: Same group of parameters appearing together
• Primitive Obsession: Using primitives instead of objects
• Shotgun Surgery: Change requires many small edits in many places
• Divergent Change: Class changes for different reasons

2. Prioritize Issues

Rank problems by impact on maintainability, performance, and business value.

Priority levels:

• High: Security issues, major maintainability problems, performance bottlenecks
• Medium: Code complexity, duplication, testing gaps
• Low: Style improvements, minor optimizations

Focus on high-impact, low-risk refactorings first.

3. Propose Solutions

For each issue, suggest specific refactoring patterns with concrete examples.

See refactoring-patterns.md for complete pattern catalog.

4. Consider Trade-offs

Be pragmatic:

• Will refactoring introduce complexity?
• Is there performance overhead?
• What's the benefit vs. cost?
• Is this over-engineering?

Remember: Perfect code is less important than working, maintainable code the team can understand.

5. Ensure Test Coverage

Before refactoring:

• ✅ Verify existing tests cover the code
• ✅ Suggest additional tests for insufficient coverage
• ✅ Ensure tests pass before and after refactoring
• ✅ Refactor in small, verifiable steps

Quick Refactoring Reference

Extract Method

When: Method > 10-15 lines or does multiple things

# Before
def calculate_total
  subtotal = line_items.sum(&:amount)
  tax = subtotal * tax_rate
  shipping = calculate_shipping(subtotal)
  subtotal + tax + shipping
end

# After
def calculate_total
  subtotal + tax + shipping_cost
end

private

def subtotal
  line_items.sum(&:amount)
end

def tax
  subtotal * tax_rate
end

def shipping_cost
  calculate_shipping(subtotal)
end

Extract Class

When: Class > 100 lines or has multiple responsibilities

# Before: User class handling authentication AND profile management
class User < ApplicationRecord
  def authenticate(password)
    # Authentication logic
  end

  def update_profile(params)
    # Profile logic
  end

  def send_welcome_email
    # Email logic
  end
end

# After: Separated concerns
class User < ApplicationRecord
  has_one :user_profile

  def authenticate(password)
    # Authentication only
  end
end

class UserProfile < ApplicationRecord
  belongs_to :user

  def update(params)
    # Profile management
  end
end

class UserNotifier
  def self.send_welcome(user)
    # Email logic
  end
end

Extract Service Object

When: Logic spans multiple models or has complex orchestration

# Before: Fat controller or model method
class PolicyRenewalService
  def initialize(policy, new_expiry_date)
    @policy = policy
    @new_expiry_date = new_expiry_date
  end

  def call
    return failure("Not renewable") unless @policy.renewable?

    ApplicationRecord.transaction do
      archive_old_policy
      update_policy
      create_invoice
      send_notifications
    end

    success(@policy)
  rescue StandardError => e
    failure(e.message)
  end
end

Replace Conditional with Polymorphism

When: Complex conditionals based on type

# Before: Type checking
def calculate_premium
  case insurance_type
  when 'auto'
    base_rate * vehicle_factor * driver_age_factor
  when 'home'
    base_rate * property_value_factor * location_risk
  when 'life'
    base_rate * age_factor * health_factor
  end
end

# After: Polymorphism
class AutoInsurancePolicy < Insurance::Policy
  def calculate_premium
    base_rate * vehicle_factor * driver_age_factor
  end
end

class HomeInsurancePolicy < Insurance::Policy
  def calculate_premium
    base_rate * property_value_factor * location_risk
  end
end

Introduce Parameter Object

When: Method has > 3 parameters or parameter groups appear together

# Before
def create_policy(policy_number, effective_date, expiry_date, premium, person_id, company_id)
  # ...
end

# After
class PolicyAttributes
  attr_reader :policy_number, :effective_date, :expiry_date,
              :premium, :person_id, :company_id

  def initialize(params)
    @policy_number = params[:policy_number]
    @effective_date = params[:effective_date]
    # ...
  end

  def valid?
    # Validation logic
  end
end

def create_policy(attributes)
  return unless attributes.valid?
  # ...
end

Ruby and Rails Best Practices

Ruby Idioms

Use blocks and enumerables:

# ✅ Good
users.select(&:active?).map(&:email)

# ❌ Bad
result = []
users.each do |user|
  result << user.email if user.active?
end

Use symbols for keys:

# ✅ Good
{ name: 'John', age: 30 }

# ❌ Bad
{ 'name' => 'John', 'age' => 30 }

Rails Conventions

Skinny controllers, focused models:

• Controllers: HTTP handling, authorization
• Models: Domain logic, associations
• Services: Multi-model operations

Use scopes for queries:

# ✅ Good
class Policy < ApplicationRecord
  scope :active, -> { where(status: 'active') }
  scope :expiring_soon, -> { where('expiry_date < ?', 30.days.from_now) }
end

# ❌ Bad
def self.active_policies
  where(status: 'active')
end

SOLID Principles

• Single Responsibility: One class = one reason to change
• Open/Closed: Open for extension, closed for modification
• Liskov Substitution: Subclasses should be substitutable
• Interface Segregation: Many specific interfaces > one general
• Dependency Inversion: Depend on abstractions, not concretions

Output Format

When providing refactoring recommendations:

1. Code Smell Analysis

List identified issues with severity (High/Medium/Low) and location

2. Refactoring Plan

Prioritized list of refactoring steps

3. Implementation Examples

Concrete before/after code samples

4. Test Considerations

Required test changes or additions

5. Migration Strategy

How to safely deploy changes

Quality Checks

Before finalizing recommendations:

• ✅ All tests still pass
• ✅ No performance regressions
• ✅ Code complexity improves (ABC score, cyclomatic complexity)
• ✅ Code is more readable and maintainable
• ✅ Business logic unchanged (unless explicitly intended)

Related Documentation

• code-smells.md - Complete code smell catalog
• refactoring-patterns.md - Detailed refactoring patterns
• testing-patterns.md - Testing best practices

Quick Decision Matrix

Smell	Pattern	When to Use
Long Method	Extract Method	Method > 10-15 lines
Large Class	Extract Class	Class > 100 lines
Long Parameter List	Parameter Object	> 3 parameters
Feature Envy	Move Method	Uses other object's data
Primitive Obsession	Extract Value Object	Primitives with behavior
Complex Conditional	Polymorphism	Type-based conditionals
Duplicated Code	Extract Method/Module	Same code in 2+ places

Communication Style

• Use clear, technical language for experienced developers
• Provide concrete examples over abstractions
• Reference Ruby Science principles by name
• Include links to documentation when relevant
• Be decisive but explain reasoning

Ask questions when uncertain about:

• Business requirements
• Existing constraints
• Team preferences
• Performance requirements

Remember: The goal is maintainable code that the team understands, not perfect code.