Name Recognition

Dear reader:

After being heads down in the code for quite a while now, we decided to dedicate a little time to sharpening our writing skills. In the coming weeks you should see a number of contributions covering a wide variety of topics. We’ll kick things off today with a seemingly pedestrian subject: the naming classes, files, variables, packages, etc.

Developers can be classified into two types.

Type 1: the naming stickler. This type considers naming to be a very important aspect of writing and maintaining code. These people will often take the time to rename variables and files that other developers created, because it bugs them to see imprecise or misleading names in the codebase. They often have strong views about how to name, and they view themselves as authors writing code for others to maintain in the future. In their view, poorly named code (even when it runs perfectly well) is poor code, because it is difficult to maintain.

Type 2: the naming sloth. Another camp is more relaxed about naming. They value getting the code working over names. In my experience, these people are often pretty good at reading complicated code. They also might not have strong feelings about what constitutes a “good name”, so they settle for whatever comes to mind.

I’d like to argue that at as developers, we should all be in the first camp without exception, and for every project. There are a few reasons for this:

1) The code is a lasting impression of the work we have created. At developers this is our core product, along with customer service.*
2) Other developers who come after us will need to maintain our code. Easy to read code adds value for your customers because the code is more maintainable.
3) People will badmouth your abilities if you do not take the time to name things properly, even if you are a supernaturally talented engineer. You don’t want to be known as the code slob.
4) Proper naming and organization will help you understand your own code in the future.

Naming is an essential part of software development.

For those of us who speak English as a second language, proper naming can pose added challenges. Nonetheless, it is still important and will require extra effort. If you are not a native speaker, it is a good idea to reach out to someone who is if you are uncertain. A brief 30 second conversation could greatly improve the usefulness of your code, and it will help you improve your English – the language of Isaac Newton and Mr T!

Note that convention trumps inventiveness when it comes to naming. Always.

This means that if plurals are used for table names in the database, you should stick with plurals. If someone before you has 20 classes in a package called “JumboServiceUser”, “JumboServiceProduct”, “JumboServiceAuth”, etc, then name your service “JumboServiceXxx”. This is important, even though “Jumbo” adds no value (I would go with “AuthService”, personally). The other alternative would be to refactor everything, which is great if you have a few minutes to do so.**

Why? Because when the code is uniform, it is easier to read, and for the reasons outlined above we need to consider ourselves authors who are concerned about others reading our code.

Commenting: Probably another topic, but my take is that comments should be used when you are doing something strange, in-obvious, or something that deserves clarification. Comments for the sake of commenting clutter up the code and usually don’t keep up with refactoring. They can rapidly become outdated and annoying.

That’s all for now. Happy naming!

* if you are an “in house” developer, your customer is probably your product manager
** If the original author is available, it’s a good idea to explain your plan to them before making changes. The human ego can be surprisingly sensitive about the way those bits are arranged!