Martin Belev

How would you feel when someone calls you a bad name?

Choosing bad names for our variables, functions, etc. can relate to the feeling 👆.

Let's explore 6 things that can help to improve our naming and why it is so important.

Link to this heading

1. Intention revealing names

The chosen name should answer the following questions:

• why it exists?
• what does it do?
• how it's used?

Don't be afraid to use long names as well. It's better than comments, abbreviations, etc.

For example:

1// ❌
2// responsible for deciding if verification modal will be displayed in days
3const seven = 7;
4
5// ✅
6const verificationVisibilityThresholdInDays = 7;

Link to this heading

2. Prefer explicit over implicit names

🔴 Implicit names assume we have additional knowledge to understand it - e.g. know the answers of the intent revealing names.

🟢 By using explicit names this should be understood from the name itself.

Implicit example:

1// Very simple code but hard to understand because of it's implicit nature.
2// The code requires us to know additional details in order to understand it.
3const filter = (list) => {
4  return list.filter((item) => item.value === 'A' || item.value === 'K');
5};

Explicit example:

1const aceValue = 'A';
2const kingValue = 'K';
3const twoHighestValueCards = [aceValue, kingValue];
4
5const filterTwoHighestValueCards = (cards) => {
6  return cards.filter((card) => twoHighestValueCards.includes(card.value));
7};

Link to this heading

3. Distinguish variable names

• avoid using conflicting information - e.g. don't name a variable list if it's not a list
• avoid numbering - e.g. var1, var2, etc.
• avoid adding noise words that are not providing any value - e.g. theUser, ageNumber.

Link to this heading

4. Pronounancable names (avoid using abbreviations)

If we think about the association between literature and code, we should be able to read easily our code.

We can't do this if we are not able to pronounce the names that we are using in our code.

Link to this heading

5. Use developer aware language when possible

There are a lot of terms that almost all developers know. It's a common language between use.

Try to use them when you choose your naming - take for example design patterns.

Using a domain term can be a fallback option.

Caveat - there are cases where it makes sense to use an abbreviation (e.g. if it's a known term for developers).

For example:

❌ Uniform Resource Locator/Identifier

✅ URL/ID

Link to this heading

6. Keep the naming consistent

Avoid using the same wording for different things. This can be confusing and make other developers wondering what's the difference between them.

Instead, try to come up with 1-1 mappings for your concepts.

For example - if you are calling something a "service" or a "controller" or whatever, make sure that all other things that are named like that are referring to the same thing.

You would more easily create a common developer language in the project which is important.

Link to this heading

Why naming is so important?

• It's almost certain that we are spending more time reading other people's code than writing code.

We are losing a lot of time in wondering what a variable does when it's "encrypted" and doesn't have an intent-revealing name.

• If the lost time is not enough, getting the wrong understanding of what the variable is doing could do more harm.

Chances for introducing a bug are increasing a lot which is 🚩.

We can not completely protect ourselves from bugs but at least we can try to reduce the chance.

• The cost for maintenance of the project and adding new features is 📈.

The cost is very high because our software becomes hard to understand and it's slowly becoming unmaintainable.

Adding even a small new feature can take days/weeks.

At the end of the day, the most important thing is to produce value for our customers.

And by having unreadable and hard to understand and maintain code, there is no chance for doing this with confidence, in an effective and timely manner.

Link to this heading

Conclusion

Naming is hard, it requires really good descriptive skills, it takes a lot of time to get good at but it's worth it and will pay off.

Other devs will appreciate your efforts for sure, as well as you will theirs.

This is not a complete list but just a few points to think about.

Hopefully, you're convinced of the importance of naming and its huge role in programming and can help to come up with better names by spending more time on it.