Skip to content

I'll Be Backend

Search lessons / @illbebackend

Code smells · Ruby

Long parameter list: introduce a parameter object

Group the values that travel together, so a new one stops touching every signature.

15 steps5 chapters~6 min at 1.25×#long parameter list#data clump#parameter object#method signatures

Language

Java Kotlin C#C++Python Ruby PHP TypeScript Go Rust Swift+1 soon

The lesson plays right here. Pause anywhere, step back, or jump to a step below. Watch the Ruby video on YouTube Code on GitHub

Watch the narrated video

Every step

Problem

Steps 1–4

Refactor

Steps 5–9

Payoff

Steps 10–11

Ruby bonus

Steps 12–13

Recap

Steps 14–15

The code: before and after

Before

WAREHOUSE_POSTAL = "10115"
WAREHOUSE_COUNTRY = "DE"

class ShippingService
  def initialize(rates)
    @rates = rates
  end

  def quote(from_postal, from_country,
            to_postal, to_country,
            weight_kg, length_cm, width_cm, height_cm,
            express)
    cost = price(from_country, to_country,
                 weight_kg, length_cm,
                 width_cm, height_cm, express)
    Quote.new(from_postal, to_postal, cost)
  end

  private

  def price(from_country, to_country, weight_kg,
            length_cm, width_cm, height_cm, express)
    volumetric_kg = length_cm * width_cm * height_cm / 5000.0
    rate = @rates.per_kg(from_country, to_country)
    cost = rate * [weight_kg, volumetric_kg].max
    express ? cost * 1.5 : cost
  end
end

class Checkout
  def initialize(shipping)
    @shipping = shipping
  end

  def shipping_for(cart, customer)
    @shipping.quote(
      WAREHOUSE_POSTAL, WAREHOUSE_COUNTRY,
      customer.postal_code, customer.country,
      cart.weight_kg, cart.length_cm, cart.width_cm,
      cart.height_cm, cart.express
    )
  end
end

After

WAREHOUSE_POSTAL = "10115"
WAREHOUSE_COUNTRY = "DE"

Address = Data.define(:postal, :country)

Parcel = Data.define(:weight_kg, :length_cm,
                     :width_cm, :height_cm, :fragile) do
  def billable_kg
    volumetric_kg = length_cm * width_cm * height_cm / 5000.0
    [weight_kg, volumetric_kg].max
  end
end

class ShippingService
  def initialize(rates)
    @rates = rates
  end

  def quote(from, to, parcel, express)
    cost = price(from, to, parcel, express)
    Quote.new(from.postal, to.postal, cost)
  end

  private

  def price(from, to, parcel, express)
    rate = @rates.per_kg(from.country, to.country)
    cost = rate * parcel.billable_kg
    cost *= 1.2 if parcel.fragile
    express ? cost * 1.5 : cost
  end
end

class Checkout
  def initialize(shipping)
    @shipping = shipping
  end

  def shipping_for(cart, customer)
    from = Address.new(WAREHOUSE_POSTAL, WAREHOUSE_COUNTRY)
    to = Address.new(customer.postal_code, customer.country)
    parcel = Parcel.new(weight_kg: cart.weight_kg,
                        length_cm: cart.length_cm,
                        width_cm: cart.width_cm,
                        height_cm: cart.height_cm,
                        fragile: cart.fragile)
    @shipping.quote(from, to, parcel, cart.express)
  end
end

Transcript, step by step

Problem

Step 1: A quote with nine parameters Before

At checkout, this method asks the shipping service for a quote. It passes the warehouse address from two constants, then the customer's address, then five values from the cart. The quote method takes all nine, and hands seven of them on to the price method. Price works out a volumetric weight from the box size, charges for whichever weight is larger, and adds half again for express.

Step 2: One flag, five edits Code smell

The carrier now charges twenty percent more for fragile parcels. Price needs a fragile flag, so the quote method, the call inside it and the checkout call all have to carry one there. A long parameter list is a method that takes so many values that every caller must line them up in the right order. You can see it here in the quote signature, here in the price signature, here in the call inside quote, and here in the checkout call. Quote uses two of its ten values itself, and the other eight pass straight through to price.

Step 3: Two booleans side by side Code smell

One new value cost four edits to signatures and calls before we reached the one line that uses it. And now express and fragile sit side by side as two booleans in every list. If someone swaps them, Ruby runs it without a complaint, and the customer pays the wrong surcharge. Ruby's keyword arguments could name each value, but these methods take them by position, so the checkout call never has to.

Step 4: Back it out, then group Plan

Let's back that change out and refactor first. Look at which values travel together, because the same groups show up in every list. The origin postal code and country always come as a pair, so do the destination's, and so do the weight and the three box sizes. A group like that is called a data clump, and Introduce Parameter Object turns each clump into one small type. We'll do it one clump at a time, and after each step the code runs and the price comes out the same.

Refactor

Step 5: The origin becomes an Address Introduce Parameter Object

The origin comes first, so we define a small Data type called Address, with a postal code and a country. Quote and price now take one Address called from, where they took two strings. Quote reads the postal code from it, and price reads the country. Checkout builds that address from the two warehouse constants.

Step 6: The destination is an Address too Introduce Parameter Object

The destination is the same kind of clump, so it reuses the same Address type. Both methods take from and to now, and the quote reads both postal codes off them. Checkout builds the second address from the customer.

Step 7: Four numbers become a Parcel Introduce Parameter Object

The last clump is the weight and the three box sizes, so they become a Data type called Parcel. Four numbers leave both signatures, and quote takes four parameters where it took nine. Checkout builds the parcel from the cart, next to the two addresses. Price now reaches into the parcel four times to work out the weight it charges for.

Step 8: Name the weight rule Extract Method

That weight rule deserves a name, so we extract it into a private method called billable kg. Price multiplies the rate by billable kg, and no longer cares how that weight is worked out. But the new method reads four values from the parcel and never touches the service's own state.

Step 9: The rule moves onto Parcel Move Method

So it moves into Parcel, where those four values live, and leaves the private section because price now calls it on the parcel. Inside the Data block it reads the parcel's own members, and price asks the parcel for its billable weight. Quote and price take four parameters each now, and the call between them fits on one line.

Payoff

Step 10: Fragile, in three edits Payoff

Now the fragile surcharge goes back in. Fragile is a fact about the parcel, so it becomes one more member of Parcel. Checkout passes the cart's flag where it builds the parcel, and price adds the surcharge, so that's three edits, each where the value is made or used. The quote signature, the price signature and the call inside quote didn't change.

Step 11: Why the clumps paid off Payoff

Each data clump is one type now, so a new fact about the parcel joins Parcel, and quote, which only passes values on, stays the same. And the two booleans no longer sit side by side, because express is a parameter and fragile lives inside the parcel. Passing the whole cart and customer would look shorter, but the origin is warehouse constants, and the shipping service would then depend on checkout's types. Two addresses can still be swapped, though, and the next lesson on domain types takes care of that.

Ruby bonus

Step 12: Four numbers by position Code smell

The signatures are short now, but checkout still fills the parcel by position, with four numbers and a flag in a row. Put the width where the weight goes, and Ruby runs it without a word, because both are numbers.

Step 13: Checkout names every value Keyword arguments

Since Ruby 3.2, a Data type's new method takes keyword arguments as well as positional ones. So checkout names each value, a width in the weight slot reads wrong at a glance, and a missing or misspelled name makes Ruby raise an error. Nothing forces callers to write it this way, so it's worth it here, where four numbers sit in a row, and Address keeps its two values in the order everyone writes them.

Recap

Step 14: Where we started, where we ended Before / after

On the left, quote took nine parameters and handed seven of them on to price. Two country strings, four numbers and a boolean sat in a row, and any two of the numbers could trade places without Ruby noticing. On the right, two small Data types hold the clumps, and the weight rule lives in the parcel. Quote and price take four parameters each, and fragile is already in.

Step 15: When to reach for it Takeaways

Reach for a parameter object when the same group of values goes through several methods in the same order. Skip it for a method with a few unrelated values, like a log call with a level, a message and an error, because a wrapper would group things that don't belong together. You'll spot it by the same names repeated across signatures, long runs of numbers or strings, and methods that only pass their parameters on. Ruby's Date already works this way, so subtracting two dates gives you the days between them, where you could have juggled six numbers.