The names you choose in programming

Naming things in programming is at least as important and as hard as knowing the syntax of a language

It’s been only five months that I have started my journey into web development at Launch School and I have already realised something that might be one of the hardest and most important skills a developer can acquire: naming things in programming.

Picking meaningful names for variables, methods and classes seems to be a trivial task when compared to complex concepts a fully-fledged web developer needs to master. However, naming things appropriately can be crucial in setting ‘good’ and ‘bad’ code apart. This is a skill that will helps programmers write maintainable and clear code. Software Engineers spend a good portion of their time reading, maintaining and debugging code. All these tasks require a good understanding of what each thing — variables, objects, classes and methods — means and what is their purpose. Choosing clear names will result in code that reads well and can be easily maintainable and reusable.

Who remembers what they ate, did or said last week? Imagine that piece of code you wrote a year ago? Your ‘future self’ will be on the same boat as someone who is reading your code for the first time and will also appreciate the names you choose in programming.

What makes a good name in programming?

They are accurate and they do what they promise they will do. For example, if you are working on developing a card game, don’t name a method shuffle_card when you are just selecting a random element in an array (this is what I did once!). Think of what you are trying to achieve with each method and each variable and name them accurately to describe that.

What your methods do and what your variables contain are clear and each function precisely indicates its purpose, so much so that you don’t have to search for the meaning in other parts of the code. When reviewing your work pretend that you do not know what else is in your code, only that atomic piece should be self-explanatory.

Prefer shorter names, but do not abbreviate for the sake of making them shorter. In shortening names, you might be compromising on meaning. For example, does ‘cust_cat’ stand for ‘customer_category’ or ‘custom_catalogue’ or ‘customer_catalogue’? Moreover, in abbreviating names, you will almost certainly be selecting ambiguous options.

Ambiguity can be one of the most frustrating experiences for whoever is reading or reviewing your code because they will probably have to guess, search or ask around for the precise meaning these things.

Same goes for foreign words or words that are too general or abstract. When starting to learn about programming it is common to come across variable names such as ‘foo’ or assignments such as ‘a = 3’. There is nothing wrong with that since the lesson is mostly trying to convey the idea that you could have picked anything to replace those values. However, they are both too general and abstract to be used in any other context than the classroom.

Programming is a creative process that requires precision and clarity and as with any piece of work, should be made accessible and interesting. If people find it easy to read, they will be more inclined to reuse, maintain and could even learn from it.

How to get better at naming things?

I found that the best advice is to practice with the deliberate purpose of getting better at it. For example, understanding the domain area and industry terms you are working on; carefully selecting meaningful names; getting people to read your code and appreciating their feedback could all help.

It’s also important — although it might sound obvious, to review your own work if it was the first time you were reading it and as if you did not know what was in the other parts of the code.

Is the effort worth it?

These suggestions may all sound very time-consuming and probably too much effort. However, the effort is worth it.

Naming things with precision and clarity saves a lot of effort from whoever reads, reviews and consumes your code. Initially, choosing the right name could take time. However, as with anything — if you want to get better at it the more you practice, review and try the better (and faster) you will get at it.