What is the point of code review?

Most software engineers have strong feelings about code review. Almost everyone would agree that it’s a best practice when working on a team, but it can also be a burden and a source of disagreements.

Too often discussions about code review focus on how to do it without stopping to ask why we do it. The process gets in the way of the purpose, and we forget why we do code review in the first place.

Whether you’re doing over-the-shoulder reviews, GitHub Pull Requests, or mailing diffs, a good code review process should achieve two things:

1. Share knowledge
2. Reach consensus

Sharing Knowledge

The difference between code review and static analysis is the discussion. When you send out some code for review you’re sharing knowledge in two directions.

First, you’re sharing your approach with your reviewers. By examining your bug fix or new feature implementation they’ll learn more about the codebase and more about the problem you are trying to solve. Often the best way to gain comfort in a new project is to observe a few code reviews and see how things are done.

Second, you’re asking your reviewers to bring their knowledge to the table. They can help you avoid mistakes they’ve made in the past. If you’re new to the project maybe they can point out missed opportunities for testing or refactoring. In the end the code will represent the best efforts of you and your reviewers combined, a whole more than the sum of its parts.

Code reviews are extremely effective for knowledge sharing because they have such concrete scope. You’re not discussing engineering in the abstract, you’re discussing techniques and tradeoffs to solve a particular problem while trying to also leave the code better than you found it.

Reaching Consensus

A code review over when the author and reviewers reach consensus. This does not mean that every single line of code has been formally approved. It means that the reviewers have had a chance to ask questions and make suggestions and the reviewer has addressed all concerns.

The hardest part about reaching consensus is knowing when you’re there! This is where code review tools can be very helpful. Not only do you need the binary approval of your reviewers, but you also need to make sure that all discussions are resolved.

Teams with high levels of trust can reach consensus really quickly. For example a reviewer can say: “This looks great, just extract this one block to a helper function” and approve the change while leaving one “unresolved” comment. The author can do the requested refactoring and resolve the comment without needing to go back to the reviewer for a second round of approval. The change is ready to submit after a single back-and-forth and the review tool has a record of the discussion.

It’s all about trust

In the end you need to trust your teammates. When an author sends out code for review they should be confident that it’s nearly ready to submit and that their reviewer will give constructive feedback. When a reviewer leaves a comment they should trust the author to implement the changes without standing over their shoulder. Approval should be granted as soon as the two parties have reached an understanding.

If you share knowledge and reach consensus in every review you will build trust and your team will never dread another review.

If you write code on GitHub and you’re looking to improve your code reivews, check out CodeApprove which is designed from the ground up for better, faster code reviews.