How to Improve Your Code Reviews

How to Improve Your Code Reviews
How to Improve Your Code Reviews

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.

How to Improve Your Code Reviews
Ingredients for a recipe by Jasmin Sessler

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

I can’t tell you how many times I found simple mistakes by proofreading my pull requests. Most tools such as GitHub, Bitbucket, or Azure DevOps contain tools to proofread your diff before sending your pull request.

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:

  • Robustness
  • Correctness
  • Design
  • Maintainability
  • REST API design
  • Globalization
  • Performance
  • Security
  • Scalability
  • Testability

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.

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.

Reference:

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].

Share this on...

Rate this Post:

Share:

Topics:

Code

Tags: