(I sent this post to my list a few months back. If you like it, and want to read more like it, you should sign up!)

I ran into a weird situation the other day with one of my apps.

Say you have an Article model, and these articles are first created as drafts. These drafts should be lightweight. You want to be able to create and edit them right away, without needing a body, or even a title.

But when you publish these articles, you need to have some extra validation. They should have a title, a body, and all the rest of that stuff.

You could write up a bunch of if statements to do the checking yourself. But you wouldn’t have all the nice form handling you get from Rails. And I’ve found that going with Rails for the things Rails handles well will save you a lot of headache later on. Is there still a way to use validations for this?

if and unless?

Validations support :if and :unless parameters, but this isn’t always so clean:

app/models/article.rb
1
2
3
4
5
6
7
8
9
class Article < ActiveRecord::Base
  # validate in draft mode
  validates_presence_of :author_id

  # validate only when published
  validates_presence_of :body, unless: lambda { |o| o.draft? }

  ...
end

Besides, this isn’t the way I want to publish an article. I want to think about publishing an article as an action, not a state the article is in, so setting and checking an attribute isn’t the right answer.

A little-known, lightly documented Rails feature

This problem is a perfect fit for Rails’ validation contexts. I first learned about custom validation contexts from a gist DHH wrote. But it was hard to find a good explanation of what these were, and how to use them.

The documentation for custom contexts is pretty thin. The only mention of it I could find in the API docs was here. And the API docs for these validations don’t mention custom contexts at all! This makes it especially hard — if you don’t know what something’s called, how do you find more documentation on it?

I finally found a good overview here: http://blog.arkency.com/2014/04/mastering-rails-validations-contexts/. It’s worth a read. Let’s see what it looks like for our example:

app/models/article.rb
1
2
3
4
5
6
7
8
class Article < ActiveRecord::Base
  # validate in draft mode
  validates_presence_of :author_id

  # validate only when published
  validates_presence_of :body, on: :publish
  ...
end
app/models/article_controller.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class ArticleController < ApplicationController
  respond_to :html

  def create
    @article = Article.create(article_params)
    respond_with @article
  end

  def publish
    @article = Article.find(params[:id])
    @article.attributes = article_params
    @article.save(context: :publish)
    respond_with @article
  end

  private
  def article_params
    params.
      require(:article).
      permit(:body, :title, :author_id)
  end
end

Not too bad! The only weird thing is having to use save instead of update in the publish method. That happens because update can’t take a validation context as a parameter. (Maybe that’s an opportunity for a pull request?)

Beyond saving

Custom validation contexts are useful for more than just saving a record in different ways. Contexts work with valid?:

1
@article.valid?(:publish)

so you can use validation contexts anywhere you want to answer the question: “Does this object have this property? And if not, why not?”

DHH creates a method ending in -able? that delegates to valid?(:context)). I really like the look of that:

app/models/article.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class Article
  validate :has_been_published, on: :view
  validate :is_not_spam, on: :view

  def viewable?
    valid? :view
  end

  private

  def has_been_published
    if published_at.future?
      errors.add(:published_at, "is in the future")
    end
  end

  def is_not_spam
    if is_spam?(body)
      errors.add(:body, "has been detected as spam")
    end
  end
end

This way, when you check it, you get more information than just true or false:

1
2
3
unless @article.viewable?
  # @article.errors is now filled out
end

Is the article viewable? Well, why not?

Just lightweight enough

There are a few other ways you could get this kind of validation behavior. You could build custom ActiveModel service objects with their own validations. You could use :if or :unless on your validations. But like a lot of the stuff in Rails, custom validation contexts are a good compromise between readability and flexibility.

The Rails 4.2 announcement had some interesting news about the upcoming Rails 5: It’s probably going to require Ruby 2.2. Which will make it the first Rails version to take advantage of all the good stuff from Ruby 2.

The post mentioned garbage collected symbols and keyword arguments. But to me, one of the most interesting Ruby 2 features is Module#prepend.

The good (and bad) of alias_method_chain

When I first learned Rails, alias_method_chain totally blew my mind. It really showed off how flexible Ruby could be.

With just a single line of code, you could completely change the way a method worked. You no longer needed to hack around libraries to add the code you wanted, you could just add it on the fly. alias_method_chain led to my first patches to gems, which led to my first pull requests, which led to my first open source contributions.

But just like monkey patching, alias_method_chain got overused, and its problems started to become obvious:

  • The method names it generates are confusing, which makes errors hard to find and debug. For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class Person
  def greeting
    "Hello"
  end
end

module GreetingWithExcitement
  def self.included(base)
    base.class_eval do
      alias_method_chain :greeting, :excitement
    end
  end

  def greeting_with_excitement
    "#{greeting_without_excitement}!!!!!"
  end
end

Person.send(:include, GreetingWithExcitement)

If you had an error in Person#greeting, the backtrace would tell you that an error actually happened in Person#greeting_without_excitement. But where is that method even defined? I don’t see it anywhere. How do you know which greeting method is the one with the bug in it? And the method names get even more confusing the more you chain.

  • If you call alias_method_chain twice with the same parameters on the same class, you could cause a stack overflow. (Can you see why?) This doesn’t normally happen, as long as your require statements are consistent about which paths they use. But it’s super annoying if you frequently paste code into a Rails console.

  • And the rest of the things described by Yehuda Katz’s blog post. This post convinced a lot of Rails devs to start abandoning alias_method_chain in favor of module inheritance.

So, why is it still used?

You can replace most alias_method_chains by overriding those methods in a module, and including those modules into your child classes. But that only works if you want to override your superclass, not your class itself. That is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class ParentClass
  def log
    puts "In parent"
  end
end

class ChildClass < ParentClass
  def log
    puts "In child"
    super
  end

  def log_with_extra_message
    puts "In child, with extra message"
    log_without_extra_message
  end

  alias_method_chain :log, :extra_message
end

If you ran ChildClass.new.log, you’d see:

1
2
3
In child, with extra message
In child
In parent

if you tried to use modules instead of alias_method_chain, you could get the output to be:

1
2
3
In child
In child, with extra message
In parent

But you cannot match the original output without changing the log method in ChildClass. Ruby inheritance doesn’t work that way. Well, it didn’t.

What changed in Ruby 2.0?

Until Ruby 2.0, there was no way to add code below a class, only above it. But with prepend, you can override a method in a class with a method from a module, and still access the class’s implementation with super. So, using our last example, we could get the original output with:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class ParentClass
  def log
    puts "In parent"
  end
end

module ExtraMessageLogging
  def log
    puts "In child, with extra message"
    super
  end
end

class ChildClass < ParentClass
  prepend ExtraMessageLogging
  def log
    puts "In child"
    super
  end
end
1
2
3
In child, with extra message
In child
In parent

Perfect.

If prepend is still hard to wrap your head around, think of it as doing something like this:

1
2
3
4
5
class NewChildClass < ChildClass
  include ExtraMessageLogging
end

ChildClass = NewChildClass

Except it won’t mess with your class names, and it affects objects that already exist.

(Yes, you can reassign class names in Ruby. No, it’s probably not a great idea.)

What does this mean for Rails?

So, the last excuse for using alias_method_chain is gone in Ruby 2.0. We could take one of the few remaining examples of alias_method_chain in Rails:

rails/activesupport/lib/active_support/core_ext/range/each.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'active_support/core_ext/module/aliasing'

class Range #:nodoc:

  def each_with_time_with_zone(&block)
    ensure_iteration_allowed
    each_without_time_with_zone(&block)
  end
  alias_method_chain :each, :time_with_zone

  def step_with_time_with_zone(n = 1, &block)
    ensure_iteration_allowed
    step_without_time_with_zone(n, &block)
  end
  alias_method_chain :step, :time_with_zone

  private
  def ensure_iteration_allowed
    if first.is_a?(Time)
      raise TypeError, "can't iterate from #{first.class}"
    end
  end
end

and replace it with a module, instead:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'active_support/core_ext/module/aliasing'

module RangeWithTimeWithZoneSupport #:nodoc:

  def each(&block)
    ensure_iteration_allowed
    super(&block)
  end

  def step(n = 1, &block)
    ensure_iteration_allowed
    super(n, &block)
  end

  private
  def ensure_iteration_allowed
    if first.is_a?(Time)
      raise TypeError, "can't iterate from #{first.class}"
    end
  end
end

Range.send(:prepend, RangeSupportingTimeWithZone)

It’s cleaner, Range#each doesn’t get renamed, and ensure_iteration_allowed isn’t monkey-patched in.

Use inheritance, not patches

Ruby gives you a ton of flexibility, and that’s one of the reasons I love it. But it also has a powerful object model. So when you want to inject your own code, try leaning on modules and inheritance before you hack it in. Your code will be much easier to understand and debug, and you’ll avoid some of the harder-to-detect side effects of something like alias_method_chain.

alias_method_chain was one of the coolest methods I was introduced to in Rails. But its days are numbered. We’ve outgrown it. And I’m not going to miss it when it’s gone.

No app survives first contact with actual users. Once people start to use it, they’re going to run into errors.

So, once in production, most apps will have a way of tracking and reporting errors. You could go simple with exception_notification or use a webapp like Honeybadger or Raygun.

But soon, you’ll see the same few exceptions over and over. Maybe a web service you depend on isn’t totally stable. Or the people using your site typo’d their email, so none of your messages are going through. Exceptions should be exceptional, they should be unexpected. But how unexpected can an error be if you see it thirty times a day?

There are better ways of solving these problems than reporting and ignoring. Most noisy exceptions fall into a few basic categories. And for each of these categories, you can use patterns to cut down the noise and make your users happier at the same time.

The network is down!

Few apps work alone. Most communicate with other apps. But when your geolocation API goes down or ec2 has a hiccup, you don’t want to get spammed with thousands of exceptions that you can’t do anything about.

When you deal with unreliable services, try the Circuit Breaker pattern, from Michael Nygard’s Release It:

The basic idea behind the circuit breaker is very simple. You wrap a protected function call in a circuit breaker object, which monitors for failures. Once the failures reach a certain threshold, the circuit breaker trips, and all further calls to the circuit breaker return with an error, without the protected call being made at all.

So, when a service goes down, you’ll automatically stop trying to connect to it. You’ll just go on without that functionality. You can even make it self-healing, so your app will automatically check the service again after a certain amount of time.

The circuit breaker pattern is designed to prevent cascading failures, but you can also use it to limit exception notifications. With this pattern, you really only need to get notified when it trips and when it fails to recover. It can turn thousands of exceptions into a few. If that’s still too many, you can tell the breaker to only report after it’s failed a few retries in a row. (Or find a different, more reliable service!)

Using this pattern takes work, but it also makes the experience better for your users. Instead of a hard error page, they’ll see a message saying that this feature isn’t working right now, and they should try again later. It’s better information for them, delivered at the right time.

Turns out gmaaaail.com isn’t what you meant

Another kind of exception I see a lot comes from bad user data.

For example, say someone typo’d their email when they signed up. They said, “justinweiss@gmaill.com”, but meant “justinweiss@gmail.com”. The first could theoretically be a valid email address, but all the emails you send bounce. And you get notified about those bounces by your email provider.

These notifications are just noise.

Instead, take a two-sided approach. Prevent the bad data up-front, and disable the feature and notify the user if it fails later on.

For email, I’ve used the mailcheck-js gem to spellcheck things like “gmail.com” and “yahoo.com” when new users register:

Then, if an email still bounces later on, turn off email to that user.

Once you turn the feature off for someone, you also need to tell them that it’s disabled and how to fix it. A banner on the top of the site is usually a good answer. Something like “We weren’t able to send your last few emails, so we’ve turned off sending emails to you. Click here to update your email address, and we’ll turn them right back on.”

You’ll get better data, and the user’s emails won’t just go into the void. Way better than those errors you’ve just been ignoring.

404s and RoutingErrors

You probably want to know about broken links or assets on your site. But those things don’t belong in your exception tracker.

For these, and other “half-expected errors”, batch them up and handle them all at once. You don’t need to get notified about them as they happen. You want pull, not push.

Things like RoutingErrors and 404s can be handled with something like Google Webmaster Tools, which will show you the pages Google knows about that are throwing 404s. Or you could run something like link-checker to check the links on your site as part of your pre-release process.

Exceptions should be actionable

It should be rare to get an exception email. Too much noise in your error tracker will keep you from seeing and fixing real problems right away.

If you’re more annoyed than embarrassed about the exceptions you see, you have a noise problem. Use the patterns here to cut down on that noise and give your users a better experience at the same time.

I’ve talked about a few of the noisy exception categories I’ve seen most often. But I’m sure I haven’t seen them all. Which exceptions annoy you the most in your apps? Do they fit into any of these categories, or do they define a new one? How do you keep them from bothering you a few hundred times a day?

The first beta of Rails 4.2 was announced last week, and it already looks amazing. I’m really excited to use ActiveJob, Web Console, Adequate Record, and Foreign Key support in my own apps.

But the beauty of Rails is in the details. And if you do a little digging, you’ll find some less advertised features that will totally improve your daily work with Rails.

Easily load config files

OK, I might be biased. But having a built-in way to load config files is going to be awesome.

config_for, new in Rails 4.2, works exactly like you’d expect:

config/redis.yml
1
2
3
4
5
6
7
8
9
development:
  host: localhost
  port: 6379
test:
  host: localhost
  port: 6379
production:
  host: redis-production
  port: 6379
1
2
irb(main):001:0> Rails.application.config_for(:redis)
=> {"host"=>"localhost", "port"=>6379}

That is, if you call config_for(:redis), it’ll look for config/redis.yml in your Rails app, parse it, and returns the right configuration for your RAILS_ENV.

It even lets you put ERB in your yaml:

config/redis.yml
1
2
3
4
5
6
7
8
9
development:
  host: localhost
  port: <%= ENV['REDIS_PORT'] %>
test:
  host: localhost
  port: <%= ENV['REDIS_PORT'] %>
production:
  host: redis-production
  port: <%= ENV['REDIS_PORT'] %>
1
2
3
4
$ REDIS_PORT=6380 bin/rails c
Loading development environment (Rails 4.2.0.beta1)
irb(main):001:0>  Rails.application.config_for(:redis)
=> {"host"=>"localhost", "port"=>6380}

If you configure lots of services in your app, this’ll make your initializers much easier to read.

Bootstrapping your apps

Most Rails apps need you to run some commands before you can try them out. Even mostly-empty Rails apps still need the database to be set up before they’ll boot.

So, Rails, once again going with convention over configuration, created a place specifically for your setup code: bin/setup.

The default is good. But bin/setup is also the place to put any other code you need to get your app started up.

So now that this is the convention, if you’ve already written a bootstrap script for your app, rename it to bin/setup, so people using your apps can get started easily.

bin/setup gives you one less decision to make when you generate new Rails apps. And once you get in the habit of running bin/setup after you git pull, you’ll never have to remember to run rake db:setup when you generate a new app again.

Transform your hash values

This is another thing I need often enough that I wish it was built-in to Ruby. When you call transform_values on a hash, it acts like calling map on the hash values, and returns a new hash with the original keys associated with the replaced values:

1
2
3
h = {a: 1, b: 2, c: 3}

h.transform_values { |v| v * 2 } # => {a: 2, b: 4, c: 6}

Simple enough. But you’d be surprised how often it comes in handy.

Bonus: More configuration!

Rails 4.2 offers a simple way to set your own global configuration:

1
2
3
4
Rails.application.config.x.some_configuration_key = "Some Value"

Rails.application.config.x.some_configuration_key # => "Some Value"
Rails.configuration.x.some_configuration_key # => "Some Value"

This works especially well when you combine it with config_for:

1
2
app_config = Rails.application.config_for(:app)
Rails.application.config.x.block_phone_calls = app_config["block_phone_calls"]

And there’s more!

It looks like Rails 4.2 is set up to be an amazing release. But it’s the little refinements that make it so great to work in Rails every day. So, if you haven’t yet, take a quick look through the 4.2 Release Notes and see which other helpful improvements you can find.

(And if you do find some cool stuff, don’t keep it to yourself. Share it here, so we can all learn something new!)

Rails’ i18n library is more powerful than it looks. You don’t need to only use it for translation. The i18n library is useful anywhere you want to decouple the text you display from the place you display it.

While I’ve been at Avvo, we’ve used i18n to do some really cool stuff. I’m going to share a few of the things that we learned that have come in handy, along with a crazy abuse of the library that ended up working out incredibly well for us.

Automatic HTML escaping

Do you have lines that look like:

1
<%= raw(t('form.required_field_header')) %>

in your views? You don’t need that raw, because if your translation key ends with _html, you get escaping for free:

1
<%= t('form.required_field_header_html') %>

Simple, and more consistent with your other t() calls.

Accessing locales more conveniently

When you build your locale files, you’ll probably have some of your keys grouped under the same parent:

1
2
3
4
5
6
en:
  bugs:
    index:
      new_label: "File a new bug"
      edit_label: "edit"
      delete_label: "delete"

To reference a bunch of these all together, you could reference them by their full key:

1
<%= t('bugs.index.edit_label') %> | <%= t('bugs.index.delete_label') %>

That’s pretty annoying and repetitive. But t() helpfully takes a scope, so you can reference keys more conveniently:

1
2
<% bugs_scope = 'bugs.index' -%>
<%= t('edit_label', scope: bugs_scope) %> | <%= t('delete_label', scope: bugs_scope) %>

If you name your partials well, you don’t even need to specify the scope:

app/views/bugs/index.html.erb
1
<%= t('.edit_label') %> | <%= t('.delete_label') %>

That is, .edit_label references bugs.index.edit_label, because you’re in bugs/index.html.erb.

ActiveRecord backends

Sometimes, static translations in a yaml file just won’t work for your project. If you use the ActiveRecord i18n backend instead:

config/initializers/locale.rb
1
2
require 'i18n/backend/active_record'
I18n.backend = I18n::Backend::ActiveRecord.new

you can look up translations in a translations table in your database. This way, you don’t have to define all your translations up-front. Instead, you can add new translations on the fly.

Setting up the translations table requires a specific migration. The README on the i18n-active_record repo has all the information you need to get it working.

Sharing partials between object types

At Avvo, we have a lawyer directory, attorney reviews, and legal advice. But a few years ago, we didn’t just have lawyers on our site. We had doctors and dentists, too!

A lot of our UI was the same between these professions. But enough was different (for example, what lawyers call “practice areas”, doctors call “specialties”), that it would be hard to share the same views or partials without some pretty ugly code.

Eventually, we thought about trying to lean on the i18n system for this. After all, English lawyerese is kind of a dialect of English, and doctorese is the same way. We didn’t want to block ourselves from eventually using other languages, so we decided to create two new locales: en_jd and en_md.

This turned out to be easy to set up as a custom i18n backend:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class AvvoI18nStore < I18n::Backend::Simple
  def translate(locale, key, options = {})
    begin
      default = options.delete(:default)
      super(locale, key, options)
    rescue I18n::MissingTranslationData => e
      # fall back to "en" if we can't find anything under "en_jd", etc.
      fallback_locale = locale.to_s.split("_").first
      super(fallback_locale, key, options.merge(:default => default))
    end
  end
end

I18n.backend = AvvoI18nStore.new

And defining translations was just as easy:

1
2
3
4
5
en_jd:
  practice_area: "practice area"

en_md:
  practice_area: "specialty"

It worked great for translating entire partials, too (note the filename):

app/views/questions/_answer_badge.en_jd.html.erb
1
<!-- Lawyer badge HTML -->
app/views/questions/_answer_badge.en_md.html.erb
1
<!-- Doctor badge HTML -->

And it even fell back to the en locale, for shared translations:

1
2
3
en:
  leaderboard:
    title: "Leaderboard"

When you were in the “Doctors” section of the site, we changed the default locale to :en_md, and vice versa:

1
I18n.locale = :en_md

And everything just worked!

I’m not sure I’d recommend this. It’s a little nuts, thinking of different professions having different languages. But it worked amazingly well while we did it. And it reveals just how much power simple tools like i18n can have.

Where do you pick up this stuff?

Last week, I talked about taking deep dives into specific technologies as a way to move from a beginner to an expert. This is another example of that: most of what we learned about i18n we learned from reading the Rails guides and API docs.

So, take that extra step. Learn the tools you rely on well. You’ll find that you’ll run into conveniences and tricks that will not only make you more productive, but might unlock brand new categories of solutions you’d never even have thought of otherwise.

So, you’ve finished a few Rails tutorials. You might have taken a class or two or watched some screencasts. You’ve followed along and built a copy of some tutorial apps. It’s pretty clear that it’s time to move to the next level in your Rails development.

Somehow, though, you’re stuck. There are tons of books, classes, and videos for people just starting out. But where are all the tutorials for intermediate Rails devs?

It’s not like it was before

Once you pass the beginner, “building baseline knowledge” stage of being a Rails developer, the resources dry up. Why is that?

Becoming an intermediate Rails developer is nothing like being a beginner. It might seem like it’s just a little different, with some more complicated stuff to learn. But passing through the intermediate stage of learning is a totally separate process.

Don’t think of it as, “A beginner knows this stuff. An intermediate developer knows all that stuff a little better, plus some extra things off to the sides.” For an intermediate developer, learning is more focused. Instead of knowing a little about a lot, you’ll learn a lot about a little.

Find a few areas to focus on. Learn more details about testing and TDD. Learn a few of the design patterns that Rails encourages, in depth. Learn about how you should design a great data model. But don’t learn it all at once. Learn one thing at a time, and learn it really well.

Once you understand the Rails basics, you’ll know enough to read API documentation, even if you don’t understand all of it yet. You could read the best books on TDD, even if they’re not written specifically for Rails. After you’ve seen enough examples of Ruby code, you can go source-diving and understand parts of Rails at a level that few others do.

When you concentrate on learning one thing well, there are many more resources to learn from. And each thing you learn will make every other thing easier to learn.

(If it seems easy for people to pick up their third or fourth language, this is one reason for it. A lot of the core concepts stay the same, which means there’s a lot less you have to learn to travel through the intermediate stage in a new language).

How do you choose what to play with next?

If you’re going to learn one thing at a time, you have to choose what to focus on first. But how do you pick, when there’s so much to learn?

Doesn’t it always seem easier to learn something when you’re interested in it? It definitely does for me. So, what’s the best way to force yourself to be interested in learning something new?

Write your own apps! Lots and lots of apps. Write apps, modify apps, add features to existing apps.

When you write an app, you will get stuck. You’ll get stuck a lot. But that’s a great thing! You should learn to love the stuckness, because it means you’re about to learn something new. Being stuck is awesome, and the more you can enjoy it, and even seek it out, the faster you’ll become an expert.

Once you research, learn, and write a solution, try to do it again in another app. Try to write it without looking at the documentation. Really learn it. Then, continue building your app, and watch for the next place you get stuck.

I love learning this way, because you get to focus on the stuff you’re going to run into most often. You’ll learn faster, because you’re not just studying to study. You’re trying to figure out how to solve a problem. And isn’t that why you fell in love with software development to begin with?

But you can’t get them all this way

After you understand the basics of Rails, you can learn serendipitously. If you understand what intermediate and expert Rails devs are talking about, you can accidentally run into conversations that will take your studying down really interesting paths.

So, when I get past the beginning, tutorial stage of learning something new, I subscribe to a bunch of blogs. I follow some of the leaders of the community on twitter. I subscribe to the WhateverWeekly newsletter for the language (RubyWeekly, iOS Dev Weekly, JavascriptWeekly, etc.).

You don’t have to read it all. You shouldn’t read it all. But let good stuff hit your radar, and try to read and follow the things that seem interesting. I’ve learned some really great tips this way, and they’ve led me into some useful topics I might not have encountered until much later.

So, what are you going to learn next?

If you’re feeling stuck because you can’t find great intermediate resources, take control of your learning. Start building an app, and pay attention to how you build it. Try something you’re only halfway sure will actually work, and seek out places you can get stuck. Use that stuckness, and find API docs, guides, or tutorials on just that small part. Go source-diving if you need to. (It might feel weird at first, but the more you look at Rails code, the more comfortable you’ll feel with it).

Really understand a small part, become an expert in it. And then, move on to the next thing.

You want to test-drive some code, but you’re stuck. Maybe you’re not totally sure what your object’s interface should look like. Maybe you’re distracted by another sunny summer day. You might not be sure you can test what you’re thinking of building. Or you could be procrastinating, because you just don’t feel like writing tests right now. How do you get the benefits of TDD when you don’t feel like TDDing?

Prototyping, or building one to throw away

“Where a new system concept or new technology is used, one has to build a system to throw away, for even the best planning is not so omniscient as to get it right the first time. Hence plan to throw one away; you will, anyhow.” — Fred Brooks

Sometimes, when I start a new feature, I’ll feel paralyzed when I think about writing my first tests. There are so many decisions to make about how the API should look, which patterns and practices will be most appropriate, and how it should all fit together.

I have a few ways I get started when I’m stuck like that. Building a prototype is another.

When you write a prototype, you should think of it like a sketch. Brainstorm and try things out. Don’t bother with tests or TDD yet. Instead, explore the decisions you’re having a hard time making, with code. Try out a few patterns, and see which of them fit the feature you’re trying to design. Figure out where the shaky parts of your app are, what needs more thought, and what you were worrying about for no real reason.

Then, throw it away and rebuild it. This time, using TDD and your newfound knowledge about how you can best build the feature.

You know when you accidentally run git checkout -f after you wrote something, and you get that feeling like you just got kicked in the stomach? But then you figure, this has to be built, so I guess I’ll do it again, and it turns out much better than it did the first time? This is also true with rebuilding prototypes. Now that you have some solid ideas of how the feature could look, TDDing that feature will go a lot more easily.

Reverse TDD

Have you ever run into a situation where you know how to build something, but you don’t know how to write the tests for it first? Or maybe it’s a one-line change to a method, but it might need some tweaking, so you don’t want to lock it down with a test before you know what the change will actually look like?

There’s a simple process that helps a lot with these situations:

  1. Write the code, without tests.
  2. Write a test for the code. Make sure it passes.
  3. Comment out the code you wrote, or revert the file you made the code change in.
  4. Run the test again. Make sure it fails.
  5. Write the code again. Run your tests. Make sure they pass.
  6. Refactor the code, taking advantage of your new tests.

I think of this as Reverse TDD or Green-Red-Green-Refactor. You won’t get the “test-driven design” part of TDD, but you’ll still get to see your tests fail when your code is broken. That’s important, because you can’t trust tests that don’t fail at least once.

Reverse TDD usually works best with tiny changes that don’t need much design. Think bugfixes, or changes that are localized to a single line, method, or class. But I use this technique a lot, especially for small changes that I’m still playing with.

The Pairing Game

The Pairing Game is a great way to break out of your Red-Green-Refactor routine when you have another developer around. It works like this:

  1. Find a partner.
  2. You write a test that will break.
  3. Your partner tries to fix that test with the simplest code possible.
  4. You write another test that will fail on that code.
  5. Your partner writes code that will pass that test.
  6. Repeat…
  7. At some point when the tests are green, you can choose to refactor some code instead of writing a test.
  8. After refactoring, swap tester and coder positions.

I’ll let you in on a secret: playing the Pairing Game on a bowling score calculator is how I originally learned TDD. It’ll help you practice writing simple code based on failing tests, and writing those tests to begin with. Both developers will learn a lot about each other’s coding style and favorite techniques. And you’ll hit flow almost immediately, which means you’ll feel great when you finish.

You might not produce code as quickly, but it’s a lot of fun, and a great learning experience.

Stay playful and experiment

TDD shouldn’t be dogma. There are ways you can play with the core TDD concepts that can lead you to some really interesting places. And you might end up with even better code.

So experiment. Try new approaches to writing code and TDD. See how they make you feel, and what kind of code you end up with. And keep rediscovering the fun and the flow in the work you do each day.

Memoization is a technique you can use to speed up your accessor methods. It caches the results of methods that do time-consuming work, work that only needs to be done once. In Rails, you see memoization used so often that it even included a module that would memoize methods for you.

Later, this was controversially removed in favor of just using the really common memoization pattern I’ll talk about first. But as you’ll see, there are some places where this basic pattern just doesn’t work right. So we’ll also look at more advanced memoization patterns, and learn some neat things about Ruby in the process!

Super basic memoization

You’ll see this memoization pattern all the time in Ruby:

app/models/order.rb
1
2
3
4
5
6
class User < ActiveRecord::Base
  def twitter_followers
    # assuming twitter_user.followers makes a network call
    @twitter_followers ||= twitter_user.followers
  end
end

The ||= more or less translates to @twitter_followers = @twitter_followers || twitter_user.followers. That means that you’ll only make the network call the first time you call twitter_followers, and future calls will just return the value of the instance variable @twitter_followers.

Multi-line memoization

Sometimes, slow code won’t fit on one line without doing terrible things to it. There are a few ways to extend the basic pattern to work with multiple lines of code, but this is my favorite:

app/models/order.rb
1
2
3
4
5
6
7
8
9
class User < ActiveRecord::Base
  def main_address
    @main_address ||= begin
      maybe_main_address = home_address if prefers_home_address?
      maybe_main_address = work_address unless maybe_main_address
      maybe_main_address = addresses.first unless maybe_main_address
    end
  end
end

The begin...end creates a block of code in Ruby that can be treated as a single thing, kind of like {...} in C-style languages. That’s why ||= works just as well here as it did before.

What about nil?

But these memoization patterns have a nasty, hidden problem. In the first example, what if the user didn’t have a twitter account, and the twitter followers API returned nil? In the second, what if the user didn’t have any addresses, and the block returned nil?

Every single time we’d call the method, the instance variable would be nil, and we’d perform the expensive fetches again.

So, ||= is probably not the right way to go. Instead, we have to differentiate between nil and undefined:

app/models/order.rb
1
2
3
4
5
6
class User < ActiveRecord::Base
  def twitter_followers
    return @twitter_followers if defined? @twitter_followers
    @twitter_followers = twitter_user.followers
  end
end
app/models/order.rb
1
2
3
4
5
6
7
8
9
10
class User < ActiveRecord::Base
  def main_address
    return @main_address if defined? @main_address
    @main_address = begin
      main_address = home_address if prefers_home_address?
      main_address ||= work_address
      main_address ||= addresses.first # some semi-sensible default
    end
  end
end

Unfortunately, this is a little uglier, but it works with nil, false, and everything else. (To handle the nil case, you could also use Null Objects and empty arrays to avoid this problem. One more reason to avoid nil!)

And what about parameters?

We have some memoization patterns that work well for simple accessors. But what if you want to memoize a method that takes parameters, like this one?

app/models/city.rb
1
2
3
4
5
class City < ActiveRecord::Base
  def self.top_cities(order_by)
    where(top_city: true).order(order_by).to_a
  end
end

It turns out that Ruby’s Hash has an initalizer that works perfectly for this situation. You can call Hash.new with a block:

1
Hash.new {|h, key| h[key] = some_calculated_value }

Then, every time you try to access a key in the hash that hasn’t been set, it’ll execute the block. And it’ll pass the hash itself along with with the key you tried to access into the block.

So, if you wanted to memoize this method, you could do something like:

app/models/city.rb
1
2
3
4
5
6
7
8
class City < ActiveRecord::Base
  def self.top_cities(order_by)
    @top_cities ||= Hash.new do |h, key|
      h[key] = where(top_city: true).order(key).to_a
    end
    @top_cities[order_by]
  end
end

And no matter what you pass into order_by, the correct result will get memoized. Since the block is only called when the key doesn’t exist, you don’t have to worry about the result of the block being nil or false.

Amazingly, Hash works just fine with keys that are actually arrays:

1
2
3
h = {}
h[["a", "b"]] = "c"
h[["a", "b"]] # => "c"

So you can use this pattern in methods with any number of parameters!

Why go through all this trouble?

Of course, if you start adding these memoization patterns to a lot of methods, your code will get pretty unreadable pretty quickly. Your methods will be all ceremony and no substance.

So if you’re working on an app that needs a lot of memoization, you might want to use a gem that handles memoization for you with a nice, friendly API. Memoist seems to be a good one, and pretty similar to what Rails used to have. (Or, with your newfound memoization knowledge, you could even try building one yourself).

But it’s always interesting to investigate patterns like this, see how they’re put together, where they work, and where the sharp edges are. And you can learn some neat things about some lesser-known Ruby features while you explore.

(I sent this post to my list a while back. If you enjoy it, and want to read more like it, you should sign up!)

The Rails ecosystem moves fast, way too fast for print. If you’re like me, you want to learn the most recent version of your frameworks and gems. But the best resources are often a few versions behind.

These resources are still useful, though. There’s nothing like a well-edited book, screencast, or tutorial to learn a library’s API, philosophy, and structure.

For example, if the best Rails books only describe Rails 4.0, you should still start from there. When you’re learning a new gem or framework, it’s important to learn why it’s designed a certain way and how all the pieces fit together. That’s hard to get from reference documentation and blog posts, but easy to get from books.

But once you build experience with an older version of a gem, how do you get caught up?

Catching up with changes

Most popular gems have CHANGELOG files in their git repository, like bundler: https://github.com/bundler/bundler/blob/master/CHANGELOG.md. These are a great way to catch up on the big changes from version-to-version. Usually, they’re just a short summary of each major change. But they give you a starting point, so you can do more research on interesting changes.

Many changelogs reference bug numbers on GitHub. If you see an entry in a changelog that has a bug number attached, you can find the bug in the project’s Issues to understand what changed, how it changed, and why it changed.

So, how do you find changelogs? Usually, I just search google for bundler github (if I’m looking for the bundler changelog), and they’re usually on the first GitHub page you see.

If there isn’t a changelog, you can also look at the project’s README or the project’s wiki on GitHub. But since those aren’t designed to help you catch up from version-to-version, they usually take longer to go through.

Using up-to-date reference documentation

When you’re working with gems, you’ll also need to keep up-to-date reference documentation around. That way, you can look up API usage and see examples while you’re writing your own apps.

You can find API documentation for any version of any gem at rdoc.info. But for even faster doc lookup, you should check out Dash or Zeal.

I use Dash, so when I need to look up API docs, I hit option-Space, start typing, and all my gem documentation shows up instantly. It’s a change in my workflow that’s paid for itself many times over.

A few tips on Rails, specifically

Rails is a large project, and the Rails contributors do a great job of maintaining changelogs and documentation.

The Rails guides are good, and they’re also built from the same git repository as Rails, so they’re always up to date.

If you’re trying to catch up to the newest version of Rails, the release notes are the best place to start. For example, here are the release notes for Rails 4.1: http://guides.rubyonrails.org/4_1_release_notes.html

The process I usually take

Putting it all together, this is what I do when I want to get completely up to date on a new library:

  1. Read a book, tutorial, or documentation about the gem. I usually try to find the newest resource I can. While I’m reading, I build an app, practice, etc. on whichever version I’m learning.
  2. Find the project on GitHub.
  3. Read the project’s changelog, readme, or wiki to take me from the version I know to the most recent version.
  4. If I’m interested in a specific change, google around for it or go through the project’s issues to learn more.
  5. Upgrade to the newest version of the gem.
  6. Install the new gem’s documentation in Dash.
  7. Write code with it!

I don’t do all those steps all the time. But that’s generally the order I go in, and this kind of process is helpful to keep around in case I get stuck on a step or don’t know where to go next.

What if you can’t find a changelog or can’t make sense of the docs?

Sometimes you just won’t be able to get the information you need out of the gem’s GitHub repo or API documentation. When that happens, you’ll have to dive into the code and start reading it.

Surprisingly, reading code is not like reading a book. Instead of reading files from beginning to end, you have to explore the code. This is more of an art than a science, but it’s an important skill to learn. So, I’ll probably have more to say about it later!

What tricks have you learned for getting caught up on gem changes? How do you stay up to date?