Code review best practices

Collection of best practice material on improving code reviews

Code review is the bread and butter for modern software teams to maintain the health and quality of the codebase and share knowledge within the organization. However, making the process truly work is all but easy. This is why we wanted to structure the best practice material on code reviews, shaping how we approach code reviews at Swarmia.

The objective of a code review

For us, code reviews have two primary purposes.

  • Making sure that the overall code health of the code base is improving over time

  • Knowledge transfer in the organization

These two primary purposes should guide the process and tools of code reviews. For more information on the purpose and standards of code reviews, we suggest checking out this article by Google.

What to cover in a code review?

To make reviewing code easier for reviewers and maintain some code review standards, it is good to have rules of thumb on what to focus on when reviewing code. Google has published their expectations on what reviewers look for in code reviews.

Summary of Google's expectations on what to look in code reviews

  • Design: Is the code well-designed and appropriate for your system?

  • Functionality: Does the code behave as the author likely intended? Does the code behave in the right way for its users?

  • Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future?

  • Tests: Does the code have correct and well-designed automated tests?

  • Naming: Did the developer choose clear names for variables, classes, methods, etc.?

  • Comments: Are the comments clear and useful?

  • Style: Does the code follow our style guides?

  • Documentation: Did the developer also update relevant documentation?

What we would add here is that stylistic issues can be automated by linters and robust quality gates. Thus, code reviews should have only a few, if any, comments about style or formatting.

How to prepare your code to be reviewed?

Most material on code reviews is written from the perspective of the reviewer. However, code reviews also involve the author sending code to be reviewed. Michael Lynch has written a best practice guide from the perspective of the author.

Summary of Michael Lynch's best practices to prepare code to be reviewed
  • Review your own code first

  • Write a clear changelist description

  • Automate the easy stuff

  • Answer questions with the code itself

  • Narrowly scope changes

  • Separate functional and non-functional changes

  • Break up large changelists

  • Respond graciously to critiques

  • Be patient when your reviewer is wrong

  • Communicate your responses explicitly

  • Artfully solicit missing information

  • Award all ties to your reviewer

  • Minimize lag between rounds of review

Already have a working code review process but want to find ways to continuously improve?

Working code review practices can be always improved. Gergely Orosz has written an article on how to make good reviews better with a collection of ideas on getting from good to great.

Summary of Gergely Orosz's ideas to make good reviews better

  • Look at the change in the context of the larger system, as well as check that changes are easy to maintain

  • Be empathetic towards the author

  • Be firm on the principle but flexible on the practice

  • Proactively reach out to the person making the change after a first pass on the code with lots of comments and questions

  • Realize that too many nitpicks are a sign of lack of tooling or a lack of standards

  • Pay additional attention to making the first few reviews for new joiners a great experience

  • Notice when code reviews repeatedly run into timezone issues and look for a systemic solution

  • Enforce hard rules around no code making it to production without a code review