Below are the most common mistakes programmers make when naming variables and functions in their code. These examples are taken from the projects of Hexlet students. I use JavaScript for demonstration purposes only because it is the most universal language, so the examples have nothing to do with the language being used. These mistakes are found everywhere in equal proportions.
Materials underlying naming conventions:
Long story short.
It is perfect if the name alone is enough to understand what the variable stands for or what the function does, rather than how it does. If you have to study the code around that name to get an understanding, it's probably a bad name. The message here is: Don't bother me when reading your code!
File?
My «favorite» variable name is file. It's even more «wonderful» when you can't see the moment it was assigned (for example, when you pass this file into a function):
const f = (file) => {
// do something with «file»
};
What is a file? Asking this question to different people will provide different answers. Regular ones are as follows:
- File contents
- Filename
- Path of a file
- File descriptor
All of these variants actually exist. However, the latter is more common in C languages, where a file is indeed a file descriptor.
File is a bad name; it forces conversion from its name to its real meaning: «call it a file, mean a path» or «call it a file, mean a content». The proper names are filepath, filename, content.
Hungarian Notation
The Hungarian Notation is an identifier (variable and function) naming convention, which comes down to encoding the data types directly in its name: e.g. userArray. This naming is about fighting the consequence rather than tackling its cause (bad names). Let's review some typical examples.
- Arrays. Dealing with an array means we deal with a collection of some elements with names. The perfect name for such an array is the name of that element in plural: users, cars, numbers, or, at most, items. It clearly shows that we are working with a collection.
- Strings. Quite simple: if we are working with an arbitrary string, we can name it text or sentence. For more specific cases it can be char or word.
- Numbers. It's even easier: number is a number anyway. However, a name that fits the purpose of the number is certainly better: e.g. denom (denominator).
Common names
Projects often have such names as before and after (or new and old). It immediately raises the question: what before? What after? No idea what we are talking about without knowing the code. Those situations I was referring to meant the value before the change and the value after the change. In fact, it's all about naming variables to reflect this essence: valueBefore and valueAfter.
The same goes for functions. What do you think happens in the code below?
process(data);
There is no chance to guess that. There may be situations with such code being appropriate, but they are few and far between. A function must tell you what it will result in, not what it does.
getName(user);
Function as a noun
Naming functions with nouns is an antipattern, even among experienced developers. Below are examples, where the left is how it is written and the right is how it should be according to the meaning:
diff(value)=>genDiff(value)parser(data)=>parse(data)value(user)=>getValue(user)
There are relatively few commonly used words to describe different actions in programming. These include modal verbs and words like render, build, generate, show, enable, set, get, edit, and others.
This also includes mixed-up word order. Sometimes we see these versions: diffBuild, while the opposite is correct: buildDiff. First, what we do (what action), then on what (the subject the action is aimed at).
Abbreviations
It is normal to use abbreviations in programming. Words can be long and awkward, so some abbreviations are nearly commonplace. For example, naming number as num is quite usual. But sometimes you can come across rather interesting variants. I've seen these:
- empt (short for empty)
- hid (short for hide)
This abbreviation not only doesn't make it better, it makes it worse, since the full word is no longer obvious, and it can be difficult to read the name. I don't know why you would cut one letter short, but it's definitely a bad idea.
Long names, on the other hand, are usually a good choice. Don't be afraid of them. For example, Rails has functions with the following names: distance_of_time_in_words or option_groups_from_collection_for_select.
Paired vs unpaired
There are often cases in programming that are perfectly suited to antonyms (words that have opposite meanings). For example, start–end, new–old, before–after. You should know how to choose these words properly. What is an antonym for begin, for example? The right answer is end, not finish (an antonym for start), as many people think.
I constantly see pieces of code where one word is made correct, while the other remains neutral. Typical example: we have an old value and a new value. The programmer creates a pair of value and newValue. However, this is not correct. The issue is that this pairing doesn't make the connection obvious. Moreover, we should be lucky enough to guess that value means oldValue. And as you remember, a name should immediately tell you its meaning and you should not have to guess.
Additional materials
