Last few months I have spent a lot of time doing code reviews. During the code review exercise I also pair with developers to refactor and improve the quality of their pull requests (PR). I care about two things in code reviews – correctness and understandability. In this post I will not focus on correctness (I might write a future post on this). Today, I want to focus on most important aspect of making code easier to understand – good names. Most of the time that I spend in the code review is coming up with the intention revealing names for classes, methods, interfaces, variables, packages, modules, and Microservices. I find most developers (irrespective of experience level) struggle to come up with good names.
There are only two hard things in Computer Science: cache invalidation and naming things.
Phil Karlton
In this post I will list three reasons I think developers struggle to come up with good names.
Reason #1: Developers don’t read their code
Coming up with a good name is an iterative process. The first name that comes to your mind is not always the best name. You have to give some time to yourself to come up with the right name.
Writing and rewriting goes hand in hand. To rewrite you have to first read what you wrote the first time. Most developers just do the stuff once and move on to the next thing. They rush towards finishing the feature doing the minimal stuff required to make build and static analysis tools happy. Sadly, we don’t yet have tools that can tell us if we are using poor names.
Common things that can be easily fixed by reading the code once:
- You rename a class but forgot to change its instance name
- You were calling a method that was writing a single object now you changed the method to return a list but you still kept the variable name as singular. Another related example is when you return an optional object
- You renamed an entity class but forgot to rename service, repository, and controller classes. This happens commonly in Java Spring Boot projects
There are many such examples where you can improve the code you wrote by just simply reading the code and making the small edits. Some of these are possible using the refactoring capabilities of most editors. For example, in IntelliJ when you refactor a class/Interface it gives you an option to rename all the call sites.
One easy way to introduce code reading in your workflow is by first raising PR in draft mode and going over your changeset for such common issues. Once you are happy, publish the PR. Another way is to write the implementation, then take a break(if possible look at your code next day after sleeping over it), then read the code and make changes(to make code clear) if required, and then raise the pull request.
Code reading is just not for small renames I suggested above. When you read code you validate your mental model with the code in front of you. If you are getting confused while reading the code or failing to explain the code then you should take time to make your intent clear by choosing the right names.
Reason #2: Developers lack business domain understanding
To come up with good names you have to understand the business domain. You do that by talking to domain experts, or working with your product managers, or by searching the internet. You will be lucky if you have access to good domain experts or knowledgeable product managers. For most of us access to good domain experts is limited.
One way I have tried to overcome this limitation in the domain I am working in for the last one year is by going over API contracts and documentation of popular organizations in my domain. I am doing work in the FinTech and banking ecosystem so I have read API contracts and documentation of Stripe, PayTM, RazorPay, etc to understand how they model those concepts.
If you understand the business domain then you know which entities you have to model in your system, what relationship they will have, and which fields should be present in those entity classes. Along with that you will know the right names for those entities.
Reason #3: Developers do not understand the importance of good naming
Good naming helps in:
- Building correct understanding of the code
- Getting started with code faster
- Easier debuggability
- Avoiding confusion
- Improving communication with business folks
My rough guess is that fifty percent of all developers in a team have less than five year working experience. This percentage will be higher in IT services organisations where there is a lot of focus on pyramid structure for cost optimization reasons.
Most developers in a team are either writing their first application or if they have worked on applications earlier then they never had to maintain the code they wrote. If the seniors in the project don’t care about naming then there is a less probability that junior developers will care about it.
The PR review process (if done in a healthy spirit) is a good way to teach developers the importance of maintainable code by giving them feedback with logical reasoning. You have to help them understand why existing and future developers will have a difficult time reading/understanding their code because of poor naming.
Conclusion
To come up with good names you have to ask the following question all the time:
- Do the names (of fields, variables, parameters, methods, classes, modules, services) actually reflect the things they represent?
- What name should I use to make code clear and easier to understand?
- Which business concept is this functionality related to? How can I map business terms to code?
- What can I learn from API contracts and/or documentation of competitors?
Shekhar Gulati 