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.

They were also much less doom-and-gloom than these. Photo by Sean Foster / Unsplash

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.

This particular gold will get EVERYWHERE. Just like bad names. Photo by Sharon McCutcheon / Unsplash

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.

She's not quite there yet. Photo by Mimi Thian / Unsplash

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!

Comments

[Stepan Stulov]

Interesting article, but the golden rule of naming is indeed too open to interpretation.

The better of your code samples wouldn't pass our code review by at least these criteria:

1. You have two names for the same thing: document vs. content. Should be strictly one name for one concept and one concept for one name. Unless you refer to content as part of the document, along with other parts like header etc. Let's stick with the latter hypothesis.
2. You abbreviated document in docID. It should be documentID.
3. You omitted certain specifics from your variable name. If you have a document, of whose content's you get a byte array of (which you will then for example deserialize into an actual instance of some class), your variable should be documentContentBytes. Same for the function: it should be GetDocumentContentBytes().

Naming things in a knowledge domain is indeed an art. One comes up with metaphors (like neural network), equivalents from real life (like network ports), completely abstract things or just funny stuff. But naming things in code is a 1-to-1 projection of your knowledge domain where you have absolutely no freedom. You just need to write it down like a disciplined lawyer, to the letter. Someone coined a term "German Naming Conventions" but I won't find the article anymore.

byte[] documentContentBytes = documentRepository.GetDocumentContentBytes(documentID);

Update: got it chrisdone.com/posts/german-naming-...