Writing clean and easily readable and maintainable code takes some effort. One of the most basic parts of a program is identifiers. To make reading and changing the code easier, the naming of them has to be good.
In this article, we’ll look at some ways to name things in an easy to understand way.
Intention Revealing Names
Names have to have the intention of what you’re trying to define. This way, people will know what your identifier actually means.
Function, class, variables, and constants should all names that show what they’re used for.
would be a bad variable declaration because
x doesn’t reveal with it’s doing.
We should name it something like:
so we know that our variable actually holds the value of the number of apples.
As we can see,
numApples is much easier to understand than
Likewise, for arrays, we should name them with meaningful names. For instance:
let list = ;
isn’t a good name because we don’t what
list actually holds. Instead, we should write something like:
let fruits = ;
So we know that the array holds
Avoid Misleading Names
Names shouldn’t be misleading. They shouldn’t be leaving false clues for the reader and lead them to the wrong conclusion about your identifiers.
So we should stick with that and don’t deviate from it. Otherwise, it gets confusing fast and other developers looking at our code can easily miss the different cases.
isn’t a good variable declaration since it starts with a capital letter.
It should instead be:
The consistent convention makes code easy to read and remember.
To make identifiers distinct, we should name them in a meaningful way.
For example, if we want to copy an array from the source to the destination array, we shouldn’t write something like:
let a2 = [...a1];
since we don’t know what
a1 means. Number series naming as we had above is bad. It doesn’t reveal the intentions of the names.
Instead, we should name them for what they are. So we can write:
let destinationArray = [...sourceArray];
The code above is much clearer since we know that they’re both arrays and we know that we’re making a copy of
sourceArray and set as the value of
They’re still distinct and they reveal their meanings.
We shouldn’t add noise words like
variable in a variable. It makes the name longer without revealing additional information.
Pronounceable name are easier to remember and understand. Therefore, we should name things in a way that is pronounceable.
Also if it’s easier to pronounce, people won’t look dumb when they’re discussing about something with such names.
isn’t a good name for a variable that means generated date and time because nobody knows how to pronounce it.
Instead, we can instead write:
would be much better since it reveals more information and it’s pronounceable.
Developers often have to search through to add new code and debug. Therefore, it’s important to have names that are searchable by typing in the search box or command line.
This means that variable declarations like:
is bad since the character
a is everywhere in almost all pieces of code. This means that it’s hard to search for it when we need to.
Instead, we should write something longer and more meaningful like:
so we can search for it.
Stick to Plain English Letters and Digits
Plain English letters and digits aren’t encoded in any special way, so it won’t cause problems in different systems and we can easily search for the names.
Also, most languages have English keywords so it’s more consistent with the rest of the code.
It justs taxes people’s brains more to figure out the encoding of characters of different languages. That’s the time that can be used to read and code.
We don’t need prefixes are class and function member names since they’re already inside the class. Namespacing them with a prefix is just extra noise. Also, classes and functions should be small enough that there shouldn’t be too many members.
Most people also ignore the prefix and look straight at the name.
Therefore, something like:
isn’t any more useful than:
It just takes up more space and creates noise.
Naming things properly takes some effort. We have to make identifiers with meaningful names that reveal their intentions. Also, the convention should be consistent to reduce confusion and mistakes.
Identifiers should also be searchable and pronounceable so that people can look for them and talk about them without sounding dumb.
Characters with special encoding also shouldn’t be used to avoid extra useless effort.
Finally, we don’t need prefixes in member names since there shouldn’t be soo many that they need to be namespaced.