How to name your Ruby classes & methods using Soylent Green

Naming is not really just about naming, as per exhibit one:

class A
  attr_accessor :a1, :b1
  def a()
    "#{a1} #{b1}"
  end
end

Could you tell me what this code does? Now let’s check another sample:

class Person
  attr_accessor :first_name, :last_name
  def full_name()
    "#{first_name} #{last_name}"
  end
end

Those snippets are exactly equivalent for the machine, and none are documented – they differ only in the naming used. Even here, it already makes a world of difference – and we’re speaking of a single class with only one method.

This (voluntary stupid) sample exemplifies the difficulty of our profession: our code is executed by the machine but we write it for humans. Those humans being most often colleagues or (even worse) your future self.

Naming is hard

Naming things is frequently featured as #1 programmer’s problems, as quoted here by Martin Fowler:

There are only two hard things in Computer Science: cache invalidation and naming things.

– Phil Karlton

Look like it is hard for a lots of people, from people asking on StackOverflow to Steve Klabnik. It is hard at first. And it stays hard.

Now, imagine if you could have very clear, crisp naming each time, that would be understood by your colleagues (or your future self) easily. That would help a lot with maintaining the code base & exchanging ideas about it (remember, good names trump good comments).

Code reviews to the rescue

We’re big fans of code reviews – automated (using our own PullReview.com) and manual. The advantage of having an automated tool passing first is not to avoid doing the human part – it is about getting things out of the way before.

While code reviews are useful for a lots of things (finding bugs, discussing design, checking whether the code does what was intended), I’ve found a good numbers of my PullRequests comments to be about naming, either as questions:Image may be NSFW.
Clik here to view.

or proposals:

Image may be NSFW.
Clik here to view.

Why it works

When reviewing code, your first (conscious) or not action is to understand what is it meant to do. Good naming helps a lot for that and bad naming leads to a very clear difficulty to understand. In that aspect, code reviews are very efficient at identifying badly or misleadingly named classes or variable. In the first example, I was convinced that the class was meant to publish the result of multiples reviews in one shot. In reality, it was about publishing a single review with different publishers (we have publishers for emails, but also for GitHub statuses, for example).

The baseline is that, as names are useful to convey meaning to other people, asking another person (your reviewer, as asking your future self is a tad more complicated) is the best way to validate them.

Start today

• In your next piece of code, check that your naming is simple and expressive. Prefer being clear to being brief - your typing speed is not the biggest obstacle to your productivity. In doubt, ask a colleague to guess what your method does based on its name. If he gets it wrong, then your name is bad.

• When reviewing, try to guess what classes & methods do just by their names, and check your assumption. If wrong, propose a better name.

Image may be NSFW.
Clik here to view.

Remember: Soylent Green is People!