Quick decisions may have long-term impact
Why developers should care about naming
In my career, I faced many problems that could have been avoided if the developers had chosen a strong name. This article tries to explain why good labeling speeds up the delivery of software, and why it can be a nightmare if you do not consider it as important.
But don’t misunderstand me, I am not teaching or giving lessons to anybody, just humbly sharing some personal thoughts I learned. Below are four situations that I experienced and which have led me to take some additional minutes to name things correctly today.
Names have a long life
I worked on a project which was named after a bird, say Parrot. We had to develop a web service just for this project, but it was not taken into account that the service could be extended and reused for some future needs. The new application was thus named Parrot, and it sounded good and logical. At first.
But guess what happened when the project ended up?
The web service continued to be used but had no business-meaning anymore. Sure we considered changing its name, but it has never come as a priority and the costs were not negligible since it was publicly exposed. In the end, there were web services named Order to manages orders, or Customer to manage customers, and Parrot to manage… what, birds? Now you see why it was a poor naming.
Names can be confusing
Every developer has faced the temptation to define variables like foo, value or even a single letter like i. At first, it saves a few chars, so you can speed up your development time by reducing it of a few milliseconds of typing. Good job!
But now, if you try to read the code again, you may spend some additional time guessing what foo is. Submitting your code to a reviewer will cost even more time (and if the reviewer is a bit skilled, he/she should point to this as a terrible practice, and refuse your pull request as it’s a waste of time again, but for two people now).
Code is written only once, but is read tens of times.
Naming rather than commenting
Several developers used to add some comments in the body of methods, and it may sometimes be required by the company to write some doc for each (public) method. From my point of view, both are unnecessary if naming is good. Do you really need to write a doc for a method named getOrdersByDeliveryDate? What would you write to describe it? This method gets the orders according to their delivery date. Oh, really? Wow!
The only exception for comments is when the code may not behave as expected independently of the developer’s will. For example, if the code uses a third-party lib, or when the result of a call to an external service sounds a bit strange. In all other cases, I see no good reason to write comments, I just prefer good naming. In regards to the methods/services doc, although there are tools like Javadoc, it is only useful when exposed. And until today, I have never worked in a company that publishes its code doc, even internally. So, my advice is to focus on writing good specs, global schemes, architecture challenges or API description, but no doc about code itself.
Years ago, a colleague of mine added a comment in his code, but for some reason, he had the bad practice to write comments in French (any other language than English may lead to the same problem). The nightly build failed because of a special char in his comment. He had to offer croissants to the whole IT the next day to apologize. Waste of time and money (plus a threat to gain weight).
Speak the same language
As a developer, we may not consider this as an important point but that is a big mistake. Defining a precise vocabulary between stakeholders speeds up a lot the discussions and meetings, especially if people are not technical. Try to name things as they are used in reality. Abstractions are good but also risky as they have to be understood by someone from the business.
I remember a shy colleague in a previous position who was reporting to a busy Senior developer infamous for having little patience. I often saw this intimidated Junior developer coming to the Senior with apprehension, afraid of looking as stupid. As soon as he opened the mouth, he was searching for his words, taking a lot of time to explain something that was eventually unclear. The Senior did his best to keep calm but one day he rudely answered: “OK, return to your desk and come back when you understand your question”. This was terribly embarrassing for everybody.
I am 100% convinced that such situations could have been avoided if the developer had spoken with precise words, precise use case, setting up the context first, and then asking a clear question, with a proposal of solutions, i.e. speaking the same language. It may also have helped him to overcome his shyness. Name things properly, and understand them before you proceed onwards.
Nothing revolutionary, right?
Wrap-up
Naming is key to being efficient in your job, whatever you are working on. It speeds up the development process, knowledge transfer, meetings with non-technical people, and eventually improves your global communication.
Take some more time to think about a good name for your method, variable, service, application, route or whatever. It is an investment that you will not regret.
