“’Tis but thy name that is my enemy!” ~ Romeo and Juliet Act II, Scene II
Juliet’s timeless lament summarizes Chapter 2 in Clean Code.
The author tackles names in this section, beginning by pointing out that programmers name things all the time.
For example, I recently worked on a problem where I had to to find the sum of all the even Fibonacci numbers that are less that 4 million (See Two Down… 509 to go!). Why? Because that is what you do when you have free time on the weekend, right?
To accomplish this task, I started right in by naming the variables and arrays that I needed:
var fibArray = [1,2];
var fibArrayEven = [ ];
var sum = 0;
To be honest, I gave very little thought to what I named these variables and arrays. At the time, the names were the least of my concerns. As long as I knew what I was talking about, then everything seemed fine to me and I proceeded with my task.
From chapter 2 I learned that this is a terrible mindset to have when you are a software developer. First of all, you may not be the only person that has to use that code. Is the programmer who comes after you going to understand what your variables mean? Second, you may understand what your code means right now, but are you going to remember 6 months or a year or 5 years from now?
This is why naming matters. The author says:
“Names are everywhere in software. We name our variables, our functions, our arguments, classes, and packages… We name and name and name. Because we do so much of it, we’d better do it well.”
According to the author, names in a program should “reveal intent”. This means that by looking at the names used in a piece of software you should instantly understand “why it exists, what it does, and how it is used.” If a name requires explanation, then the programmer’s intent is not clear enough.
Lets go back and examine the names that I used in my program.
var fibArray = [1,2]
Because I knew I was working with the Fibonacci numbers, this name for my array seemed to make pretty good sense to me. But what about someone unfamiliar with the problem. Would they immediately know that the purpose of this array is to eventually store Fibonacci numbers? Maybe/ maybe not. It depends on the person and perhaps their mathematical background. Math people might automatically assume that “fib” is short of Fibonacci, but what about those among us that are inclined toward language? They might think I am writing a program about lying!
It would be better for my code if I were explicit about the name of this array. The author, Robert Martin, says, “Clarity is King!”
I could very easily improve the name of my array:
var fibonacci_Numbers_Array = [1,2]
That is better. It is clear from the name that this array will store Fibonacci numbers.
But it turns out that clarity and intent are not the only things to consider, although they are the main ones. There is also brevity to consider. It would hardly be useful if we needed a full paragraph to define a single variable!
Martin says, “Shorter names are generally better than longer ones, so long as they are clear.”
Oh boy. Now my array name is looking too long to me. This naming business sure isn’t easy. The trick is to wed intent, clarity and brevity. Here is another option for my array:
There. That looks better. The name is shorter, clear, and explicit in its intent.
“O! be some other name:
What’s in a name? that which we call a rose
By any other name would smell as sweet;
So Romeo would, were he not Romeo call’d,
Retain that dear perfection which he owes
Without that title. Romeo, doff thy name;
And for that name, which is no part of thee,
Take all myself.”
Slow down there Juliet. Perhaps Romeo remains the object of your affection if his name were say Bob (though that doesn’t seem to have the same romantic effect) but when it comes to programming, names matter! To “retain that dear perfection” in code we can not just toss names around any way we want!
Martin goes on to list other considerations for writing excellent names. Some of these recommendations are over my head at the moment. I look forward to discussing these more technical points during the book club so that I can learn from the more experienced programmers. Here is a brief list of additional things to keep in mind when naming your variables, functions, classes, etc…
Names should be:
- Avoid Encoding ???
- clear, not cute (no slang, colloquialisms, or culture-specific puns)
“I take thee at thy word.
Call me but love, and I’ll be new baptiz’d;”
I am picking up some great advice from this book. As much as possible, I am trying to put the advice into practice by altering my own bad code and trying to transform it into better, cleaner code. I guess I am now an evangelist for the gospel of writing clean code and I am newly baptized 🙂