Almost twenty years ago, I started as a developer in a company that used code reviews. At that time, I had never done a code review nor was my code ever reviewed.
For my first project, I had to create a COM component in C++ using the ATL framework. ATL uses reference counting to manage the lifetime of an object. Reference counting means that you have to call
Release() when you are done using the object. If you forget to call it, it results in a memory leak.
I remember the result of my first code review as if it was yesterday. It was dramatic.
I don’t remember the exact number, but I am sure there were more than 100 review comments. The reviewer mentioned every
Release() I forgot. The tone of the review was harsh. I struggled with it.
Was I such a terrible developer?
Currently, I have been doing code reviews for more than a decade. Performing code reviews is the best method to improve the quality of your codebase and create a culture of learning and respect.
Yet there is a specific recipe for successful code reviews.
Improve Your Code – Why Are Code Reviews Critical?
Open the last book you read about programming or another technical topic and look for a paragraph titled Acknowledgments at the beginning of the book.
I am sure that in this paragraph, the author thanks his editor for helping to create a better version of the book. Editing and reviewing is the standard procedure when writing a book.
Why isn’t this the same for software development?
During a code review, another developer checks your work for errors. The developer will point out improvements, such as:
- hard-to-understand code
- unclear names
- commented code
- untested code
Besides looking for improvement, the reviewer learns from the solution. You should look at code reviews as an opportunity to grow, and as a safety net — not an opportunity for criticism.
Code reviews are also known to prevent bugs. Research done by IBM² found that each hour of inspection prevented about 100 hours of related work (testing and defect correction).
Automate What Can Be Automated
Before we go on and look at my recipe for successful code reviews, we have to talk about automation.
Don’t waste time during code reviews checking for style errors. Instead, agree on a style guide and use a linter or a static analysis tool to verify that style.
Also, make sure that it’s possible to run a complete build to verify that everything still builds correctly and all the unit tests succeed.
Automating all these tasks will make the contribution from a reviewer more valuable. The reviewer can focus more on other aspects, such as functional errors and readability.
Improve Your Code – Recipe for Code Reviews
My recipe for successful code review consists of two sets of ingredients, one for the author of the changes and another set for the reviewer.
Improve Your Code – Ingredients for the Author
As the author of the changes, you have the responsibility to make it easy for the reviewer to understand your code review.
The size of the changeset should be small
Nobody likes doing code reviews that consist of thousands of lines of code changes. It will take much time, and there is a high chance that a re-review is necessary due to a large number of changes. Research¹ has shown that the size of the changeset influences the usefulness of comments. As the changeset gets bigger, the number of useful comments drops.
So make sure that the size of your changeset is small, say, less than 250 lines. The review will be of a higher quality.
Proofread your diff
As an author, you should always proofread your code changes to find common mistakes so that the reviewer can focus on other points.
Improve Your Code – Ingredients for the Reviewer
Aim for improvement, not for perfection
Try to improve the code a notch instead of making it perfect. It helps me to think about it in terms of grades. When I receive a pull request that starts at a D, I help the author to bring it to a C — not perfect but better than it was.
Won’t this degrade the entire codebase to a C? I don’t think so. I find that when I help a developer go from a D to a C, the next pull request they send will start at a C. Within a couple of pull requests, they’re sending me reviews that begin as Bs, which become As by the end of the review.
Respect the scope of the review
Simply, only review the code that was changed. If you see something near the modified code that you feel should be fixed, you can kindly ask the author to fix it. But remember that it is not in the scope of the review.
If the pull request didn’t change a line, it’s out of scope.
The tone of the review
I find the tone of the review one of the most important aspects of a code review. Always try to ask open-ended questions instead of making opinionated statements. Offer other alternatives or possible workarounds. But don’t insist on those alternatives or workarounds.
If you don’t understand something, assume that you, as a reviewer, are missing something and ask for clarification. Try to use the word consider. For example: “Did you consider refactoring this into a single method?” or “Consider renaming this method for readability.”
Review in a timely manner
Try to review the pull request as soon as possible. If you first have to finish your task, let the author know when you will start on the review.
Use a review checklist
You should try to create a checklist that can be used as a reference when performing the code review. Take a look at the following categories for inspiration about items to put on your checklist:
- REST API design
Another source for inspiration is ISO 25010, a standard that defines quality characteristics of a software system.
Improve Your Code – Conclusion
I am sure that code reviews, when done correctly, can improve your codebase and create a culture of learning and respect.
This article describes my definition of a good code review. I listed several ingredients for the author and the reviewer to make sure that you are off to a good start.
For more information, I suggest reading the following articles by other people and organizations on their code review best practices.
- Code review from Google Engineering
- How to Make Good Code Reviews Better by Gergely Orosz
- Code Review Guidelines for Humans by Philipp Hauer
- Developer’s Guide to a Better Code Review Process from SmartBear
- How to Do Code Reviews Like a Human By Michael Lynch
- Humanizing Peer Reviews by Karl E. Wiegers
Thanks for reading!
For more news check out our resource centre
About the Author:
I write and design software. I love to learn and teach. I am an Open-Source and Agile enthusiast.
Kalkman, P. (2020). How to Improve Your Code Reviews. Available at: https://medium.com/better-programming/how-to-improve-your-code-reviews-f5e9d5a6536c [Accessed: 18th September 2020].