And why naming is important.

Imagine you are writing a new code (it’s probably not hard to imagine, probably you even don’t have to imagine it whatsoever). You need a new variable with an appropriate name. Or maybe a method, yes, let’s make a method instead. A couple ideas come to your mind, but assume, for some weird reason, you want to google for it. You are very pragmatic and you want to do your best. You start looking for some common conventions. It turns out very soon that the only thing you can find is:

The rules and conventions for naming your variables can be summarized as follows: Variable names are case-sensitive. A variable’s name can be any legal identifier — an unlimited-length sequence of Unicode letters and digits, beginning with a letter, the dollar sign “ $ “, or the underscore character “ _ “.

Yes. This is what you see while searching for “how to name variables”. There are tons of guidelines describing syntax-related rules or best practices established by language creators and communities.

It’s not what we are talking about, though.

Why naming is important?

One of the greatest quotes about programming says:

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. — John F. Woods

The same concerns naming. It’s always a good idea to code for a maintainer. The reason being that maintenance is by far the most expensive phase of any project, thus, it is best to help reduce costs for the maintenance phase.

Always name parts of your code in such a way that if someone picks up the code, they will take pleasure in reading and learning from it. A little naming convention saves your maintainer a few hundred searches. A code maintainer who doesn’t have to check the use of every variable in a function to ensure that it’s not improperly named has less finding to do, and can focus more on the task at hand.

Why is it hard to name your code properly?

Beginner programmers always spend a lot of time on learning a programming language, code syntax, technology, and tools. They think, if they master the craft of technologies, they will become good programmers. However, programming is not about mastering the tools, it is about creating a solution to a problem in a particular domain and to do it in cooperation with other programmers. Therefore, it is very important to express your thoughts in code precisely and in a result to be understood by other people.

I make many code reviews each day and I see how important is to properly name our code. I also see differences among developers when it comes to their programming background and tendency to describe variables.

Objective-C verbosity

Fibonacci algorithm in C. See all of these comments?

Of course, this verbosity is not a rule. You can write a great and a poor code in any language. This is just an observation that there’s a common tendency based on a previous background.

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business, or management issue. As a result, many people in this field do not do it very well.

How to name particular parts of your code?

Names have to reveal your intentions. You should always name parts of your code to explain why it does something and not only what it does. Maybe you think about it as a little bit of exaggeration, but I really like how my colleagues name their code.

*In the upcoming article, I plan to prepare a set of ready-to-use rules directly in our code to improve its readability and reveal your intentions.

Can’t I just comment a code?

At the very beginning of my career I was pointed out that:

A comment is an apology.

A comment is an apology for not choosing a more clear name or for the failure to use explanatory variables, functions or even classes. Apologies for making the code unmaintainable. Comments should not be written. This is because the variables and method names should be self-evident. If you need to write a comment, it means your code is not self-explanatory enough. Rename it. If a name requires a comment, then the name does not reveal its intent.

You should always name your code as if comments didn’t exist. This forces you to write readable code in the simplest, plainest, most self-documenting way you can come up with.

The opposite approach

In his recent article Yegor Bugayenko presents an interesting approach, regarding maybe not strictly variables naming, but variables themselves. He points out that many variables are just unnecessary, so it’s better to create them as an anonymous instead of having them locally with assigned names.

So the more variable names I have to remember while reading through it, the longer it takes to digest the code and come to a conclusion about its purpose and effects. I think four is the maximum number of variables I can comfortably keep in my head without thinking about quitting the job.

This may be valid in some cases. New variables make the code longer because they need extra lines to be declared. And they make the code more complex because its reader has to remember more names. However, if these variables can help you understand a code more, then definitely they should be introduced.

Here’s an example from my recent project:

Firstly, I thought that this additional name is unnecessary. Fortunately, my colleague explained to me why it is important.

Subscribe to get the latest content immediately

https://tinyletter.com/KamilLelonek

Summary

Perhaps that’s the dirty little secret of naming your code: to write good names you have to be a good writer. Developers rely on comments to tell the story when they should be relying on the code to tell the story. You need to be a storyteller. Writing good, meaningful names is hard. Names aren’t meant for a compiler but to communicate ideas to other human beings.

Follow some of these rules and see if you improve the readability of your code. If you are maintaining someone else’s code, use refactoring tools to help to resolve these problems. It will pay off in the short term and continue to pay in the long run.

Resources