John Au-YeungWriting clean, 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.
Avoid Mental Mapping
Developers shouldn’t have to map their names into their meaning in their brains.
For example,
let r;
is a bad variable declaration for something that holds a URL string since there’s nothing about URL in the name r .
We can just name it url like we wanted to save the effort of mapping it in our brains.
Clarity is the most important thing when naming things.
Class Names
In JavaScript, class names are upper camel case. So FruitStand is a good name and fruitStand is not a good name for a class.
We should stick with convention to avoid confusion and mistakes.
Method Names
Method names should have camel case names in JavaScript. For example, getName is a good name for a function but GetName isn’t.
Don’t Use Clever Names
We should use clever names to confuse readers of our code. For example, holyCow is a bad variable for something that holds the number with the number of fruits since it doesn’t convey the actual content of the variable.
It makes the code hard to read and it’s not really funny.
Instead, we should name if numFruits so people actually know that the variable holds the number of fruit.
We should name things by what they mean.
Pick One Word Per Concept
We should pick one word per concept. For example, if we want to convey that a function gets a value. Then we shouldn’t have fetch, get, or grab in different function names.
Picking one word per concept reduces the mental capacity required for developers to understand the code since everything is predictable.
No Puns
Having 2 words for the same purpose in identifiers makes them confusing. Therefore, we should avoid them since they can be interpreted differently by different people.
For example, augment is a bad name for a function that can mean adding entries to arrays, or appending things to a string. So we should name it with the name that shows what it actually does.
Name that Developer Understand
It’s important to name things that developers understand. In our code, we should name things that are relevant to the domain of the solution.
For example, many developers know what a MessageQueue or Database is. Therefore, those are good names.
Problem Domain Names
If there’re no names in technical speak that developers understand, then we should name things in a way that describes the problems that we’re trying to solve.
Meaningful Context
We should name things with meaning context to our identifier names. For example, username and password are good names because we know that these variables are about the user entity which is used for logging into a system.
On the other hand, generic names like number and modifier aren’t good variables names because they don’t provide much context about what we’re set to values of these variables to.
If we’re using these names to construct a string that has the quantity of something and then the modifier for the thing we’re quantifying, then we should write something like:
let numberOfItems = 1;
let pluralModifier = numberOfItems ? '' : 's';
let numItemsString = `${numberOfItems} item${pluralModifier}`;
As we can see, these names are much more meaningful than number and modifier . They provide us with the context of the situation that the variables are used.
Don’t Add Useless Context
Useless context is also bad. For example, if we prefix every identifier with foo or Foo because we’re writing software for the company Foo, that’s bad because we already know that the software is for company Foo, so we don’t need to add the company name to everything and take up more space on the page and disk space.
We only need enough information in our names to convey the meaning of the identifier. If we can do it in a shorter way, then it’s better.
Naming things the right way takes some thought. We should add only enough context that people will gain a better understanding of the code.
Also, there shouldn’t be a need for developers to mentally map the names to something in their minds. If it’s needed then the name has to convey more meaning.
Clever names and puns are also bad since they’re misleading.
Finally, sticking to conventions of JavaScript is much needed so avoid confusion.
The post JavaScript Clean Code — More About Naming appeared first on The Web Dev.
