The subtle art of naming variables, methods, functions, classes, modules

"Design is thus about picking the right abstractions. If you choose well, your code will be expressive, understandable and flexible, and everyone will love both it and you. However, if you get the abstractions wrong, your code will be convoluted, confusing, and costly, and your fellow programmers will hate you." - Sandi Metz

There are some hard dilemmas in our society, like deciding where to go for lunch today, or whether or not to go to that party thrown by someone you don't really get along with that well, and a more common one for us developers is the dilemma of how to name variables, methods, and classes.

Stop and think for a moment: when was the last time that, while working out a solution to a problem and already having all the logic of a method in your head, you just hit a mental block where no name seemed good, until you decided to go with the first name that came to mind, and hours later, while refactoring the code, you concluded it wasn't the best name? Or even names of variables, methods, and classes that you named anyway with that code smell feeling and that were never renamed again? Yeah, maybe you've come to the right place.

This article is meant to be a summary of good practices from books like Clean Code by Uncle Bob and 99 Bottles of OOP by Sandi Metz, but it doesn't replace reading them (in fact, I strongly recommend you read these books, or at least skim through them).

Figure 1: Martin Fowler / Two Hard Things - Courtesy: https://martinfowler.com/bliki/TwoHardThings.html

Why good names matter

Good names will not only make code easier to understand in the future, they'll also help developers maintain it, avoiding the famous WTF/Minute metric coined by Uncle Bob in the book Clean Code.

The idea behind the metric is this: when facing a piece of code, how many WTFs (What The Fuck?) per minute will a developer say out loud? If the number is high, you probably have a problem in that code.

Figure 2: WTFs/m metric - Courtesy: https://www.osnews.com/story/19266/wtfsm/

So, how do you name things?

The general rule is that the name of a thing should be one level of abstraction higher than the thing itself.Sandi Metz

In my day to day, since I work a lot with TDD, I often don't really know what I'm testing or how to name the method under test. One tactic I use is to create the test and its method with any name (I usually end up using fruit names, like banana, pear, etc.). Once I finish writing the test and read it back, I can understand what that test is really testing.

Example:

it "banana" do
    first_number = 1
    second_number = 2
    banana = Math.banana(first_number, second_number)

    expect(banana).to eq(3)
end

Once we understand it, we could rewrite the test above like this:

it "sums two numbers" do
    first_number = 1
    second_number = 2
    summed_number = Math.sum(first_number, second_number)

    expect(summed_number).to eq(3)
end

Meaningful names vs. comments

A variable, method, or class should have a meaningful name that answers questions like: why it exists, what it really does, and how it is or will be used.

You should, for example, be able to look at a method and, just by reading its call, have a basic understanding of what action and result come out of that method. If it needs comments explaining it, maybe the name isn't revealing its real intent.

Example:

Bad: field :date, type: String # birth date (the name date doesn't reveal its real meaning, so it needs a comment explaining it).

Better: field :birth_date, type: String

Using abbreviations

Prefer self-explanatory, meaningful names over abbreviations. Someone who just joined the project may not understand the domain yet and get lost in abbreviations.

Example:

Bad: field :wtf, type: String # what the fuck? (the name wtf doesn't reveal its real meaning, so it needs a comment explaining it).

Better: field :what_the_fuck, type: String (just kidding... you shouldn't name methods with swear words, but it works as an example of an abbreviation).

I'm not saying you should never use abbreviations, but avoid them when it's a domain concept that isn't widely known by the general public. For example, a variable could be called url instead of uniform_resource_locator.

Style Guides

Style guides are, as the name says, a guide created by a company or person with good practices to follow in a given language.

Above I listed some good practices taken from the books I mentioned at the start of the article. I strongly recommend you look at some style guides created by the community of the language you're programming in right now.

Each language has its own style guide, often created by its developer community.

I hope this article helped clarify why good names matter in your code and how they can make a big difference in its readability and maintainability. Happy coding!