APoSD and Clean Code from a Ruby point of view

The Ruby verdict in detail

The compact Ruby rule

Where the two approaches differ

The repository records discussions held between September 2024 and February 2025. Its latest visible commit is dated 15 April 2025.12 The authors substantially agree that modularity, readability, unit testing, and professional judgment matter. Their disagreement is about trade-offs and failure modes.

Method length

Ruby’s mainstream tooling contains a strong short-method bias: RuboCop enables Metrics/MethodLength by default with a default maximum of 10 lines, while also making the threshold configurable and excluding comments by default.3 The community Ruby Style Guide similarly advises avoiding methods over 10 LOC and says most should be under five.4 These are conventions, not evidence that every eleventh line should become a new method.

Comments

Ruby guidance itself is split. The community guide opens its comment section with a deliberately anti-comment stance, but then explicitly recommends rationale comments.4 Shopify’s Ruby guide says to include missing context, keep comments synchronized, avoid superfluous narration, and focus on why.5 Ruby’s own documentation guide says too little information is bad and that documentation should quickly convey usefulness and usage.6

Test-driven development

RSpec’s own introduction strongly reflects Martin’s side: add a failing example, implement the behavior, take very small steps, and refactor before the code becomes messy.7 Rails, however, supports multiple test levels, model, controller, integration, and system tests, so a Ruby team is not limited to microscopic unit-first development.8

What Ruby changes

A Ruby-specific stopping rule for extraction

1. Extract when the new boundary has a stable name and contract that callers can use without reading its implementation.
2. Extract when it owns a domain concept, policy, external integration, or independently testable calculation.
3. Keep together when fragments share local state, loop context, ordering constraints, or one invariant.
4. Reconsider when reading the parent requires immediately opening every private helper.
5. Do not extract solely to satisfy a numerical linter threshold.

Ruby examples

Tiny methods, hidden coupling

The top-level method reads like a story, but the story is incomplete. Each helper mutates shared instance variables, so the reader must inspect all of them to learn the state machine.

class Checkout
  def call
    load_cart
    calculate_totals
    reserve_inventory
    capture_payment
    persist_order
  end

  private

  def load_cart
    @cart = Cart.find(@cart_id)
  end

  def calculate_totals
    @subtotal = @cart.items.sum(&:price)
    @tax = Tax.for(@subtotal, @cart.shipping_address)
    @total = @subtotal + @tax
  end

  # Other helpers read and mutate @cart, @subtotal, @tax, @total...
end

This is the Ruby form of Ousterhout’s entanglement concern: method count increased, but the amount of knowledge a reader must load did not decrease.

A deeper boundary with local coherence

class Checkout
  Result = Data.define(:order, :receipt)

  def initialize(pricing:, inventory:, payments:)
    @pricing = pricing
    @inventory = inventory
    @payments = payments
  end

  # Completes a checkout atomically from the application's point of view.
  # Payment capture may succeed before persistence, so callers must supply
  # an idempotency key that remains stable across retries.
  def call(cart, idempotency_key:)
    totals = @pricing.quote(cart)
    reservation = @inventory.reserve(cart.items)

    receipt = @payments.capture(
      amount: totals.total,
      idempotency_key: idempotency_key
    )

    order = Order.transaction do
      Order.create_from!(cart:, totals:, reservation:, receipt:)
    end

    Result.new(order:, receipt:)
  rescue
    reservation&.release
    raise
  end
end

This method is longer than RuboCop’s default maximum, but it keeps the orchestration order, failure path, and compensation logic visible. The extracted collaborators are deep boundaries: pricing, inventory, and payment each hide a separate body of knowledge.

Comments that earn their maintenance cost

# Weak: narrates the next line.
retry_count += 1 # Increment retry count.

# Strong: preserves a non-obvious external constraint.
# The provider may redeliver an event for 72 hours. Keep the key forever;
# expiring it can produce a second charge after a delayed retry.
idempotency_keys.insert!(provider_event_id)

TDD and bundling as complementary modes

A practical Ruby team policy

Method policy

• Use RuboCop metrics as review triggers, not automatic refactoring instructions.
• A method may exceed the threshold when splitting it would obscure ordering, shared invariants, or failure handling.
• Prefer extracting domain objects and stateless collaborators over chains of private helpers sharing instance variables.
• During review, ask “what knowledge does this boundary hide?” before asking “how many lines is it?”

An example configuration, not a universal optimum:

Metrics/MethodLength:
  Max: 15
  CountComments: false
  AllowedMethods:
    - change   # Rails migrations are declarative scripts.

Metrics/BlockLength:
  Exclude:
    - "spec/**/*_spec.rb"

Comment and API documentation policy

• No comments that merely translate syntax into English.
• Document public gem APIs, extension points, callbacks, side effects, exceptions, units, and retry/idempotency behavior.
• Explain workarounds with a version, issue link, and deletion condition.
• Keep comments close to the invariant they protect; test the invariant where practical.
• Use RBS for machine-checkable type shape and prose for semantics that types do not express.

Testing policy

• Every defect receives a regression test.
• Favor behavior-level examples over tests coupled to private method structure.
• Use request/integration tests for Rails boundaries and focused unit tests for complex policies.
• Permit short design spikes, but discard or rewrite them before merge.
• Make design review an explicit step inside red-green-refactor, not an assumed side effect.

Review checklist

The argument in their own words

Each excerpt is intentionally short. Follow the source link for complete context.

“The best methods are those that provide a lot of functionality but have a very simple interface.”

John Ousterhout, repository discussion 1

“We both value decomposition.”

Robert C. Martin, repository discussion 1

“The maximum allowed length is configurable.”

RuboCop Metrics documentation 3

“Avoid methods longer than 10 LOC.”

Community Ruby Style Guide 4

“Focus on why the code is the way it is.”

Shopify Ruby Style Guide 5

“The goal of Ruby documentation is to impart the most important and relevant information in the shortest time.”

Ruby Documentation Guide 6

“Take very small steps.”

RSpec 7

“Testing is central to the development process.”

Rails Testing Guide 8