The Naming Checklist

Naming is everywhere and everything.

In high school, I spent a good amount of time ruminating about my fake baby’s name (this was for our freshman life skills class). I’m always receptive to learning people’s names, partly to consider whether I’d like to bestow that name to my first-born child. While a criteria for naming a child may be different (is it unique, but pronounceable?) — the process for determining names still requires thoughtfulness.

But it definitely takes practice. I’ve struggled with proper naming conventions; for instance, I love calling things a “helper” when their role is much more nuanced than that. I used to also sprinkle “check” into my method names (as in, “check_for_winner”) . Once you think about it, what does check really do? What happens when you check for the winner? What does it return: a boolean value or the winner’s marker? It may be an intuitive human notion, but doesn’t make sense.

Tim Ottinger coined the phrase, “implicity of a code,” to refer to the extent by which the context is not explicit in the code itself. In other words, the code is obscure. This will happen if you have strangely-named variables, magic numbers and magic strings. An implicit code base will leave others (non-contributors of the code) scratching their heads trying to understand the significance of certain aspects of the code.

So, why is choosing good names tough? First, it requires good descriptive skills. Not only must you thoroughly understand the purpose of that method or class, but you must be able to describe it succinctly. Secondly, it requires “a shared cultural background” between you and other developers. As Ottinger affirms: “This is a teaching issue rather than a technical, business, or management issue. As a result many people in this field don’t learn to do it very well.”

A few months ago, when I first read the 2nd chapter in Clean Code (“Meaningful Names”), it changed so much of my perspective. I had such a deeper appreciation for developers. I started seeing them as writers of apps and programs. Here they were — crafters of vastly complex logic and UI, but they were also authors, weighing the meaning and importance of semantics. I figured I’d synthesize this chapter into a checklist. Whether you’re first writing your program or refactoring it for the nth time, take a look at how you name things.

At the heart of it, names should reveal the writer’s intentions. After all, explicit names will lead to better understanding of the function’s purpose and role. To say what you mean is an important rule in writing anything, but here are some tips in how to achieve that.

1. Avoid words that obscure the meaning of your code. Avoid abbreviation or shorthands that may make sense to, but not to other people. For example, don’t use “hp” to mean “hypotenuse” since that two-lettered word can easily refer to other concepts and things, like the company that makes your printer.
2. Stay away from using names which vary in small ways. It’s easy to mistaken one for the other. The book offers this example, which is pretty golden: “XYZControllerForEfficientHandlingOfStrings” and “XYZControllerForEfficientStorageOfStrings.”
3. Avoid single-letter names since they’re 1) not intention revealing and 2) they’re not searchable. I typically try to use as few words as possible and be succinct in naming, but I never try to use a single letter to represent the concept that I’m referring to.
4. Avoid lower-case L or uppercase O since they look like constants one and zero. This one I hadn’t considered, but is good. I think it goes hand-in-hand with #3; you’re not going to ever use them as single-letter names, anyway.
5. Number-series naming is not intentional. Think of “a1, a2, a3” or even “string1, string2, string3.”
6. Remove noise words, which are meaningless terms. Super-abstract words like “info” or “data” are the worst. Prefix conventions like “a” or “the” should be avoided, unless they make a meaningful distinction.
7. Use pronounceable names. I love how “genymdhms” was actually a variable name. It referred to generation date, year, month, day, hour, minute, and second — but you wouldn’t know that unless you worked there. Apparently, employees started referring to it phonetically (as in gen why emm dee aich emm ess). Yikes. This was my parents’ rule for naming me.
8. Avoid encodings and mental-mapping, which means that you’ve somehow deciphered the variable name. This requires one extra step and is an unnecessary mental burden.
9. Although this was the convention in prior generations with specific languages, don’t use Hungarian notation (including the type in its name) or member prefixes (“m_”) or indicator of interface/implementations (e.g. “IPlayer”) to indicate that `Player` is an interface.
10. Class names have noun or noun phrase names (they’re not a verb); avoid words like “manager” or “processor.” Method names should have verb or verb phrase names.
11. Don’t use colloquial language or slang or culture-dependent jokes.
12. Pick one word per concept and stick to it. For example, you may find these words to be synonyms: “fetch,” “retrieve,” or “get.” Rather than switch between them, and cause confusion, just stick to one of ‘em.
13. Avoid using the same term for two different ideas.
14. Use solution domain names (e.g. Computer Science terms, algorithm names, pattern names, math terms, etc.). Developers are familiar with them. This is why I was comfortable with calling a method “get-minimax-move.” The concept of a minimax algorithm is well-known and documented. (It also helps me succinctly describe what it does and helps me avoid a name like “get-max-value-if-computer-and-min-value-if-human.” Just kidding, I would never name anything like that).
15. Add meaningful context through prefixes. Together, certain variable names may make sense; individually, they may not. A good example is how the following variables make sense when bunched together: “street,” “city,” “state,” and “ZIP code.” But, “state” out of context can mean anything. In this case, it may make sense to add a prefix such as “address” to each variable name. But, don’t go crazy and overdo it.

And lastly, one thing I’ve learned is to not be afraid to rename things. My hesitation to do, previously, was because it would require tracing through my code and was sometimes intimidating. These days, if I think of a more explicit name, I play with it, write it out, and if I like it, I’ll change it throughout my codebase. Rinse and repeat!