This article was contributed by Avdi Grimm. Avdi has been wrangling Ruby code for over a decade and shows no signs of slowing down. He is the author of *Exceptional Ruby* and *Objects on Rails*. His next book, *Confident Ruby*, focuses on writing Ruby code with a confident and straightforward style.

Losing the plot

Have you ever read a “choose your own adventure” book? Nearly every page ends with a question like this:

  • If you fight the angry troll with your bare hands, turn to page 137.
  • If you try to reason with the troll, turn to page 29.
  • If you don your invisibility cloak, turn to page 6.

You’d pick one option, turn to the indicated page, and the story would continue.

Did you ever try to read one of those books from front to back? It’s a surreal experience. The story jumps forward and back in time. Characters appear out of nowhere. One page you’re crushed by the fist of an angry troll, and on the next you’re just entering the troll’s realm for the first time.

What if each individual page was this kind of mish-mash? What if every page read like this:

You exit the passageway into a large cavern. Unless you came from page 59, in which case you fall down the sinkhole into a large cavern. A huge troll, or possibly a badger (if you already visited Queen Pelican), blocks your path. Unless you threw a button down the wishing well on page 8, in which case there nothing blocking your way. The [troll or badger or nothing at all] does not look happy to see you.

  • If you came here from chapter 7 (the Pool of Time), go back to the top of the page and read it again, only imagine you are watching the events happen to someone else.

  • If you already received the invisibility cloak from the aged lighthouse-keeper, and you want to use it now, go to page 67. Otherwise, forget you read anything about an invisibility cloak.

  • If you are facing a badger (see above), and you choose to run away, turn to page 93…

Not the most compelling narrative, is it? The story asks you to carry so much mental baggage for it that just getting through a page is exhausting.

Code as narrative

What does this have to do with software? Well, code can tell a story as well. It might not be a tale of high adventure and intrigue. But it’s a story nonetheless; one about a problem that needed to be solved, and the path the developer(s) chose to accomplish that task.

A single method is like a page in that story. And unfortunately, a lot of methods are just as convoluted, equivical, and confusing as that made-up page above.

In the following sections, we’ll take a look at some examples of code that unnecessarily obscures the storyline of a method. We’ll also explore some techniques for minimizing distractions and writing methods that straightforwardly convey their intent.

Secure the borders

Here is some code that’s having some trouble sticking to the plot:

require 'date'

class Employee
  attr_accessor :name
  attr_accessor :hire_date

  def initialize(name, hire_date)
    @name      = name
    @hire_date = hire_date
  end

  def due_for_tie_pin?
    raise "Missing hire date!" unless hire_date
    ((Date.today - hire_date) / 365).to_i >= 10
  end

  def covered_by_pension_plan?
    # TODO Someone in HR should probably check this logic
    ((hire_date && hire_date.year) || 2000) < 2000
  end

  def bio
    if hire_date
      "#{name} has been a Yoyodyne employee since #{hire_date.year}"
    else
      "#{name} is a proud Yoyodyne employee"
    end
  end
end

We can speculate about the history of this class. It looks like over the course of development, three different developers discovered that #hire_date might sometimes be nil. They each chose to handle this fact in a slightly different way. The one who wrote #due_for_tie_pin? added a check that raises an exception if the hire date is missing. The developer responsible for #covered_by_pension_plan substituted a (seemingly arbitrary) default value for nil. And the writer of #bio went with an if statement switching on the presence of #hire_date.

This class has serious problems with second-guessing itself. And the root of all this insecurity is the fact that the #hire_date attribute is unreliable—even though it’s clearly important to the operation of the class!

One of the purposes of a constructor is to establish an object’s invariant: a set of properties which should always hold true for that object. In this case, it really seems like one of those invariants should be: employee hire date is a Date.

But the constructor, whose job it is to stand guard against initial values which are not compatible with the class invariant, has fallen asleep on the job. As a result, every other method dealing with hire dates is burdened with the additional responsibility of checking whether the value is present.

This is an example of a class which needs to set some boundaries. Since there is no obvious “right” way to handle a missing hire date, it probably needs to simply insist on having a valid hire date, thereby forcing the cause of these spurious nil values to be discovered and sorted out. To do this, it should guard its own integrity by checking the value wherever it is set, either in the constructor or elsewhere:

require 'date'

class Employee
  attr_accessor :name
  attr_reader :hire_date  

  def initialize(name, hire_date)
    @name          = name
    self.hire_date = hire_date
  end

  def hire_date=(new_hire_date)
    raise TypeError, "Invalid hire date" unless new_hire_date.is_a?(Date)
    @hire_date = new_hire_date
  end

  def due_for_tie_pin?
    ((Date.today - hire_date) / 365).to_i >= 10
  end

  def covered_by_pension_plan?
    hire_date.year < 2000
  end

  def bio
    "#{name} has been a Yoyodyne employee since #{hire_date.year}"
  end
end

In this version, the hire_date attribute is protected by type check in the setter method. Since the constructor now delegates to this setter method to initialize the attribute, it is no longer possible to construct new Employee objects without a valid hire date. Now that the “borders” of the object are guarded, all the other methods can focus on telling their own stories, without being distracted by a potentially missing hire_date.

Be assertive

In the last section we saw how assertions in a class’ constructor or setter methods can help keep the other methods focused. But uncertainty and convoluted code can come from sources other than input parameters.

Let’s say you’re working on some budget management software. The next user story requires the application to pull in transaction data from a third-party electronic banking API. According to the meager documentation you can find, you need to use the Bank#read_transactions method in order to load bank transactions. The first thing you decide to do is to stash the loaded transactions into a local data store.

class Account
  def refresh_transactions
    transactions = bank.read_transactions(account_number)
    # ... now what?
  end
end

Unfortunately the documentation doesn’t say what the #read_transactions method returns. An Array seems likely. But what if there are no transactions found? What if the account is not found? Will it raise an exception, or perhaps return nil? Given enough time you might be able to work it out by reading the API library’s source code, but it’s pretty convoluted and you might still miss some edge cases.

You decide to make an assumption… but as insurance, you document your assumption with an assertion.

class Account
  def refresh_transactions
    transactions = bank.read_transactions(account_number)
    transactions.is_a?(Array) or raise TypeError, "transactions is not an Array"
    transactions.each do |transaction|
      # ...
    end
  end
end

You manually test the code against a test account and it doesn’t blow up, so it seems your suspicion was correct. Next, you move on to pulling amount information out of the individual transactions.

You ask your teammate, who has had some experience with this API, what format transactions are in. She says she thinks they are hashes with string keys. You decide to tentatively try looking at the “amount” key.

transactions.each do |transaction|
  amount = transaction["amount"]
end

You look at this for a few seconds, and realize that if there is no “amount” key, you’ll just get a nil back. Then you’d have to check for the presence of nil everywhere the amount is used. You’d prefer to document your assumption more explicitly. So instead, you make an assertion by using the Hash#fetch method:

transactions.each do |transaction|
  amount = transaction.fetch("amount")
end

Hash#fetch will raise a KeyError if the given key is not found, signaling that one of your assumptions about the Bank API was incorrect.

You make another trial run and you don’t get any exceptions, so you proceed onward. Before you can store the value locally, you want to make sure the transaction amount is in a format that your local transaction store can understand. Nobody in the office seems to know what format the amounts come in as. You know that many financial system store dollar amounts as an integer number of cents, so you decide to proceed with the assumption that it’s the same with this system. In order to once again document your assumption, you make another assertion:

transactions.each do |transaction|
  amount = transaction["amount"]
  amount.is_a?(Integer) or raise TypeError, "amount not an Integer"
end

You put the code through it’s paces and… BOOM. You get an error.

TypeError: amount not an Integer

You decide to drop into the debugger on the next round, and take a look at the transaction values coming back from the API. You see this:

[
 {"amount" => "1.23"},
 {"amount" => "4.75"},
 {"amount" => "8.97"}
]

Well that’s… interesting. The amounts are reported as decimal strings.

You decide to convert them to integers, since that’s what your internal Transaction class uses.

transactions.each do |transaction|
  amount = transaction.fetch("amount")
  amount_cents = (amount.to_f * 100).to_i
  # ...
end

Once again, you find yourself questioning this code as soon as you write it. You remember something about #to_f being really forgiving in how it parses numbers. A little experimentation proves this to be true.

"1.23".to_f                     # => 1.23
"$1.23".to_f                    # => 0.0
"a hojillion".to_f              # => 0.0

Only having a small sample of demonstration values to go on, you’re not confident that the amounts this API might return will always be in a format that #to_f understands. What about negative numbers? Will they be formatted as “-4.56”? Or as “(4.56)”? Having an unrecognized amount format silently converted to zero could lead to nasty bugs down the road.

Yet again, you want a way to state in no uncertain terms what kind of values the code is prepared to deal with. This time, you use Kernel#Float to assert that the amount is in a format Ruby can parse unambiguously as a floating point number:

transactions.each do |transaction|
  amount = transaction.fetch("amount")
  amount_cents = (Float(amount) * 100).to_i
  cache_transaction(:amount => amount_cents)
end

Kernel#Float is much stricter than String#to_f:

Float("$1.23")
# ~> -:1:in `Float': invalid value for Float(): "$1.23" (ArgumentError)
# ~>    from -:1:in `<main>'

The final code is chock full of assertions:

class Account
  def refresh_transactions
    transactions = bank.read_transactions(account_number)
    transactions.is_a?(Array) or raise TypeError, "transactions is not an Array"
    transactions.each do |transaction|
      amount = transaction.fetch("amount")
      amount_cents = (Float(amount) * 100).to_i
      cache_transaction(:amount => amount_cents)
    end
  end
end

This code clearly states what it expects. It communicates a great deal of information about your understanding of the external API at the time you wrote it. It explicitly establishes the parameters within which it can operate confidently; as soon as any of its expectations are violated it fails quickly, with a meaningful exception message.

Unfortunately, as a result it is really telling two stories: one about refreshing transactions (remember, that’s nominally what this method is about) and one about the format of an external data source. This is quickly mended, however:

class Account
  def refresh_transactions
    fetch_transactions do |transaction_attributes|
      cache_transaction(transaction_attributes)
    end
  end

  # Yields a hash of cleaned-up transaction attributes for each transaction
  def fetch_transactions
    transactions = bank.read_transactions(account_number)
    transactions.is_a?(Array) or raise TypeError, "transactions is not an Array"
    transactions.each do |transaction|
      amount = transaction.fetch("amount")
      amount_cents = (Float(amount) * 100).to_i
      yield(:amount => amount_cents)
    end
  end
end

By failing early rather than allowing misunderstood inputs to contaminate the system, it reduces the need for type-checking and coercion in other methods. And not only does this code document your assumptions now, it also sets up an early-warning system should the third-party API ever change unexpectedly in the future.

Represent special cases with objects

The most common causes of code that tells a confusing story are special cases. Let’s look at an example of a special case, in the context of our budgeting application.

You’ve implemented transaction import and it’s working great. Except for one little problem: users have been reporting bugs about the reported balances being off. And not just the balances; in fact, all of the reports seem to have incorrect numbers for some accounts.

You do some investigation into the system logs, and eventually discover the culprit. It turns out that some banks, when they receive a authorization for a credit card charge, immediately report it as a pending transaction in the transaction list. The data looks something like this:

{"amount" =>