The Golden Rule of Variable Naming

A while back I wrote a post that I am still particularly proud of: The Ten Commandments For Naming Your Code. In it I published ten "commandments" for variable naming that I believed would help all of us get rid of bad names.

The commandments were:

1. Be specific
2. Don't use unnecessary words
3. Don't use abbreviations
4. Use the code's primary human language (e.g. don't use Spanish when everyone on your team speaks English).
5. Don't make up words
6. Don't include the variable type in the name
7. Use non-obvious words only if the meaning is obvious to your team.
8. Prefer active voice (e.g. prefer "Transform" over "GetTransformation")
9. Use consistent syntax
10. Break these rules if necessary

I still think these commandments are good guidelines, but in the four-plus years since I published that post, I've gotten a bit more nuanced in how I name my variables. I've come up with a process, a process that I can use to accurately name almost anything.

Problem was, until recently it was very difficult to describe that process to others, though. I just knew, and I didn't necessarily know how I knew. For example, I can look at this declaration and just "know" that it can be made better:

byte[] ctnt = docClass.Content(dID);

After a bit of trial and error, most likely I'll replace those names with the following:

byte[] content = documentRepository.GetContent(docID);

But if anyone were to ask me "why did you rename those variables to those specific names" the best explanation I could come up with was "because these are the only ones that sounded right" which is terribly unsatisfying.

But now, I can answer these questions not with the ten commandments above, but merely one rule: the Golden Rule of Variable Names.

The Golden Rule

So what is this golden rule? It is merely this:

Variable names should be as descriptive as necessary while still being as concise as possible.

That's all there is to it.

"But Matthew" I hear you dear readers saying, "there's still a lot of room for interpretation in that rule, isn't there?" You are correct. Naming things is an art and a skill, one that we gain only through practice and failure. This rule, while very helpful, does not account for all situations, for such a "one and only" rule would be impossible to make.

Nevertheless, it's still an enormously useful adage. Take that earlier example:

byte[] ctnt = docClass.Content(dID);

From the First Golden Rule alone, we can make the following conclusions:

1. The name "ctnt" is concise, yes, but not descriptive. This is not a word, merely a collection of letters, and is easily misinterpreted. We should replace it with a name that accurately describes what it represents.
2. The name "docClass" is pretty generic. What is this class: a service, a repository, a mapper, something else? We can't tell. We should replace this name with something that tells the reader what this class is generally supposed to do.
3. The method name "Content" is both readable and concise, but not descriptive enough. What does this method do to the content? Does it retrieve it, or update it, or delete it? We can't tell. We should replace this name with a more active name, something that spells out exactly what this method does.
4. The variable "dID" is concise but not understandable. Most likely it's the ID of a particular document, what if there are business objects such as "diary" or "dialogue"? We can't know what this is supposed to represent without digging further into the code. We should replace this name with a more descriptive one.

So, by applying the Golden Rule of Variable Naming, we can arrive at a better example:

byte[] content = documentRepository.GetContent(docID);

This is much better than we started with. It is now clear that this line of code is retrieving the stored content of a specific document from some data store.

Summary

The Golden Rule of Variable Naming helps us name our variables in such a way that other people can read our code and more easily understand the intent we were trying to convey. It's not a be-all, end-all rule, but helps us inch closer to the ultimate goal of writing readable code: understandability.

If you have other naming guidelines you'd like to share, naming horror stories you want to tell, or if you just think I'm totally wrong, please share in the comments!

Happy Naming!