Uri Shamay is a close friend and wunderkind with a wealth of experience in the devops field both as a founder and lead developer for a number of organizations. He wrote an excellent post detailing some of the most important aspects to remember when creating a code review checklist, and why it is so important in the development cycle.
Code review is the best way to maintain a high level of code quality. The code review acts not only as a gatekeeper for bad code but also as an incentive for coders to improve their skills, learn, and scrutinize their own work. Code giants like Google use code review on everything added to the codebase.
Most coders don’t use a checklist. At least not a formalized one. And definitely not a checklist as a tool produced by a team or a company that is used uniformly by all coders and reviewers. They might be using a mental checklist they have created for themselves. But this checklist may have major flaws if it is not discussed, designed, and maintained by multiple people. Checklists you can find on the internet are too long and too abstract for anyone to actually use. That is why, if you’re going to use a checklist, you should build your own.
Why use a checklist?
Code reviews need to produce changes. If they do not, they might as well not happen. This can lead to one of the biggest pitfalls of code reviews. Falling into a nitpicking session in search of something to change.
By using a checklist, the reviewers can stick to what’s important, and find those changes in the big things. Checklists also help reviewers make sure they don’t forget anything important.
When should you use a code review checklist?
A checklist can be a tool you build to improve your code reviews, or it can be more of an established company-wide practice. Either way, a checklist can be used both by the coder submitting code for review and by the person doing the review.
Preparing a code for review is an important step and a checklist allows the coder to take a step back and look at their code more objectively before handing the code on to the reviewer. I’d go so far as to say that a checklist can benefit the coder more than the reviewer.
Top tips to building an effective code review checklist
1. Mind the length
When building a code review checklist it is important to consider the length. If a checklist is too short it is unlikely to be a true checklist and cover the important things. But if a checklist is too long? It is just going to be ignored, as it would be too tedious to use.
The right size for your team might not be the same as for another. However, as a rule of thumb, 3-5 major issues and another 7-10 more entries focused or smaller issues would be a size I’d recommend.
2. Start from the basics
There are many code review checklists out there. Some are a long list of questions and some are broad topics you should make sure to touch on. Most of those issues are simply good design principles any coder should be aware of and manage while writing code. It makes sense that those would be the focus of checklists.
However, I find it unhelpful to have a checklist item that asks if the code in question is good design. Instead, I recommend including items that encourage focusing on the reasons the code was written in the first place, or give a different lens through which to review the code.
3. Prepare your code
Before you even get any explanation from the coder, ask yourself “Is this code self-explanatory?” I’m a great proponent of self-documenting code. But even if your coding style incorporates comments the code should be human-readable.
Having to read the code without any explanation forces the reviewer to make sure they can understand the code without someone explaining it to them. If any part of the code requires explanation to be understood, it might be best to break it down into smaller pieces of code or add a comment. With this item on the checklist, the reviewer can simply tell the coder that they did not understand the code. The coder can clarify, but they will know that they need to make the code clearer.
4. Affective vs effective code
Once you understand what the code does, you must ask: does the code change achieve its goal simply and effectively? People are very protective of their code, and as such will be reluctant to throw out their work and find a different solution. But if you can suggest a more effective code change? You should bring that to the attention of the coder.
5. Communicate effectively
How you communicate your proposal in a checklist is very important to whether or not it would be accepted. I find it best to ask a guiding question and let developers come up with alternative solutions. That way it is still their idea, and it will be met with less resistance. Remember, code reviews are not about showing your colleague how smart you are, it is about making the code as good as possible.
6. Don’t neglect dependencies
An often overlooked part of code review are Dependencies. It is easy to overlook a new dependency or a code in a package it doesn’t belong in. Putting this item on a checklist makes sure that this issue is not missed. This can also make the code review faster as any issues of dependencies could be resolved by the coder before submitting the code for review.
7. Consider company-specific issues
I could go on and list an endless number of issues that may or may not apply to your specific codebase. At the end of the day, your checklist needs to be tailor-made for your needs.
Does your company hold valuable information for customers? Could secrets have made their way into your codebase? Make sure you check security. Is your code highly modular, components used by many different areas of the code? Make sure everything is properly decoupled. If your company uses unit testing? Then you must make sure that the scope of the automated testing is comprehensive. Is the code change in a performance-intensive area of the software? Profiling could be a key item on your checklist.
And so on and so forth.
8. Iterate and improve
Like any design in software or otherwise, a checklist should improve over time. Put the checklist itself on the agenda of a meeting. Get feedback from everyone using it to find ways to improve it. Don’t forget to also get input from anyone that is not using it. This can help you find out why and how it can be made more accessible to them.
Sometimes a one size fit all solution will not work. Maybe another department needs a different checklist, and maybe someone in your team needs a different approach to help them improve the quality of their code review. Either way, checklists are not usually written in stone and, as such, grow and evolve with your codebase.
Creating the right code review checklist you need to do some research about what checklists are available, and take them apart. Find the items on them that speak to your company’s design and integrate them.
But most importantly, keep improving your code review checklist. The chances of you getting a perfect checklist the first time you build one are slim. Find out which bugs have slipped through the review process and add the necessary checklist items to prevent them. And cut out items that don’t produce any changes. Think of it as freeing some unused objects in your reviewer’s memory.
Top comments (0)