Reviewing code has been advertised as a great solution for improving code quality in any project. While this is true, the main advantage is in how code reviews change the way you approach your code problems. Any code can be reviewed, but there are some best practices that will make the reviews more valuable.

Why review code?

Lets focus first on why we want code to be reviewed. Understanding why code reviews are valuable should help us get the most out of a review.

In its most simple form, reviewing code is about validation. Validating if my
solution to a problem is not flawed and may be introducing new problems. Getting someone else to review your code is good way to iron out edge cases that you might have overlooked. Each team member has different experiences with the application (and code in general) and might see an impact on other aspects of the application.

Next to that code review is also the perfect way to validate if a solution is
right for that application. A solution might work but not fit the culture
or already existing best-practices. For example: an application that is build
around the command pattern might not allow business logic to be added outside that pattern.

Reviewing code, or getting your code reviewed, is a huge learning  pportunity. You’ll get see different approaches to problems or share your approach with the rest of the team. It’s a perfect platform to share knowledge. Not only knowledge about code, but knowledge about the application (its history, its business, …).

A review can:

  • expose edge cases (both in code and in the business logic)
  • expose an overseen test-path
  • validate the solution with the best-practices of the project/team/company
  • enforce consistency in solutions (ie. this project uses CommandBus)
  • start a discussion about problems with the architecture (possibly resulting in new refactoring tasks)
  • share clever solutions and new learned approaches with the team (can work inspiring)

It is tempting to put uniform code-styles as one of the goals, but I believe that that is not something that should be validated in each code-review. A team should have agreed on a rule-set beforehand and not spend any more energy on it.

Valuable code reviews

It’s all fun and games until you need to review code that consist of 64 changed files with 3000 changed lines of code. After a long time of trying to figure out the code, you’ll most likely come to the conclusion that you still don’t know what this code is actually fixing.

To be able to get the most out of a code review, it’s best to keep a few things in mind. First, reviewing small chunks of code makes it easier to see where possible problems or edge cases are hiding. I think reviewing code that has a maximum of 200-300 lines of code works best.

Second, reviewing code that solves only one problem makes it clearer to see if the solution is right for the problem. And whether it actually solves the problem. It is not recommended to ask for a review on code that solves multiple problems.

Third, assume that the reviewer has very little context. Do your best to explain what you are solving and why you are solving it. You can always link to another task or discussion, but don’t expect the reviewer to read through pages of documentation or discussions. Try to anticipate on questions they might ask. If you considered a solution but didn’t go for it, chances are that the reviewer is wondering why you didn’t do it this way.

At last, look at code review not only as a validation tool but also as a documentation tool. It doesn’t serve as application documentation but it serves for understanding why something was changed and what triggered the change. Just like git blame,
this will prove valuable in the future. At madewithlove we use changelogs (also works great for creating releases) to describe changes in a code review. In most cases this is enough, in complex cases some extra explanation is required.

How code reviews change us

If you follow those guidelines, you’ll notice that you need to think about your solution in smaller and incremental changes. It will force you to finish things in smaller blocks. You will have to isolate one change out of your problem, fix it and ask for a code review. If it’s approved, it can be deployed while you work on the next incremental change in your problem.

As a result, your code will be reviewed much more thoroughly and you’ll be able to get feedback faster. As a bonus you’ll be able to deploy faster.

Resources