Name Length & Specificity
Questions frequently arise regarding the length of variable names and specificity. After all, short names can be quicker to “read” (fewer characters to scan), but more specificity (resulting in a longer name) can communicate more understanding. There’s a tension that needs to be balanced here.
Problems with Names That Are Too Short/Generic
Names that are too short or generic tend to have the following problems:
They don’t communicate enough information to give a reader a clear understanding of what a variable represents. Super short one or two letter variable names tend to have this problem - quick to read (few characters), slow to understand (have to read a lot more code to find context/meaning). See Avoid Overly Short Names for more details.
They’re too generic and could be used for multiple purposes. Some names (ex.
date
,file
) might give a reader a decent clue as to what a variable holds. However, short names like this can often potentially be used for more than one purpose, which can lead to confusion for readers (particularly in longer blocks of code that might have many similar variable names). You want to avoid a reader being misled due to confusion on to the purpose of a variable (ex. “is this date the current date or a past date?” or “is this an input file or an output file?”). See Avoid Overly Generic Names for more details.
In summary, short names often lack sufficient information to quickly communicate enough understanding to readers without having to spend time analyzing a large amount of code. See Avoid Overly Long Names for more details.
Problems with Names That Are Too Long/Specific
Long and more specific names tend to be beneficial in that there’s a lower chance information will be missing that needs to be communicated to a reader for understanding. However, names that are longer than necessary may run into some practical problems:
They can just take longer to read - more characters to scan across.
They take up more length on a line - while monitors nowadays tend to be really wide with high screen resolutions, there’s still only a limited amount of screen real estate in which code can fit. You want to communicate the right amount of information within some given screen space.
Humans have limitations on the number of things they can keep in their head at once. The more words in a variable name, the more a human has to keep in his/her head at once to get the full meaning of a variable. There’s a point where this can become overwhelming and infeasible.
In summary, longer names can take longer to read, comprehend, and keep in your head, so names that are too long can slow down readability.
Consider Context/Scope to Balance Name Length/Specificity
To balance concerns of name length/specificity, names should be as specific as necessary within a given context (scope).
To better assess things for these decisions, it's useful to look at the "context" and "scope" of a variable when considering its name. The “context” can be thought of as the information a reader coming into some code already has in his/her head, and the “scope” is another way to think about the “size” of the context in which a variable exists.
If you're already in a class named something like MySuperSpecificWindow
, then you probably don't need to prefix all local variables within a method of that class with my_super_specific_window
- within the context (scope) of a method in that class, the fact that a variable is related to "my super specific window" is likely obvious and already in the mental scope of readers when reading a method within that class. So having to read all of those words again just slows down the reading process. Similar things often apply to member variables.
At the same time, make sure you are not using variable names that are generic enough that different variables within a context/scope could be confused with each other. A large point of specific variable names is to provide clear distinctions as to what the variables represent. If, within a given scope, there are a lot of similarly named variables that could easily get mixed up, that's likely an indication that you made need longer, more specific variable names to provide sufficient distinction. For example, using the example above about a method in a MySuperSpecificWindow
class, if that method is interacting with some other kind of window for which there are local variables, then that could be a reason to include some kind of my_super_specific_window
prefix before certain variable names. You need to provide distinction so that readers don't get confused and make errors due to mixing up variables.
Longer code tends to have a higher probability of interacting with more concepts and having more variables, so more specific names tend to be more important. Shorter code may be able to get away with some shorter names.
Tips on Name Length & Specificity
The following sections give more detailed tips on naming variables with appropriate length and specificity:
- Avoid Overly Short Names [VS1]
- Avoid Overly Generic Names [VS2]
- Avoid Overly Long Names [VS3]
- Minimize Repeating Class Names in Member Variable Names [VS4]
- Make Names Specific Enough to Distinguish Between Similar Concepts [VS5]
- Make Names Specific Enough to Distinguish Between Similar Variables [VS6]
- Name "Functional" Variables with Enough Specificity to Make Operations Clear [VS7]
- Communicate Intent in Names Where Appropriate [VS8]
- Acronyms & Abbreviations