During the last two years, I've put a lot of effort in improving the code review process at my work. While I introduced new code review tools, explained the concepts to my collegues and helped them, when they struggled, I have seen a lot of different pitfalls with code reviews. It wasn't easy to explain everyone the benefits of reviews and to bring them on a good path, where reviews become helpful for each other. I'd like to share some insights on this topic.

🎯 Code review goals

In order to learn, how you can bee good at reviews, you should understand what can be achieved with reviews. The obvious thing might be something like ensuring high code quality, but there is more:

• By studying their code, you can learn from your co-developers, how they address problems.
• By suggesting improvements, others can learn from you the same way.
• Having a look at all reviews, helps to keep track of changes in your codebase.
• Showing your code to others, helps to spread knowledge about the codebase and technologies used in the project.
• And of course: Reviews help to write better code.

To achieve this goals, I follow at least these few simple things in every code review:

📝 My ultimate code review checklist

Try to understand every single change

Go through the changes line by line and make sure you know what the change means for the code. If you do not understand whats going on: Always ask! Asking questions, even if they feel dumb, is never bad. Let the author explain the changes, until you understand what's goning on.

Try to find at least one thing that could have been done better

Even if the review is just one or two simple changes, I try to find space for improvements. This not only helps to improve the code and the project, but also forces me to understand the code deeply. But don't search too long, if you can't find any suggestions within a few minutes, continue the review.

Always add some positive feedback

Telling people they've done a good job, helps to keep the good mood up in your team. Even if some (or most) of the changes have to be refactored or are useless, you should add some positivity to the review. This helps to ease diffucult situation, espacially if you are reviewing code of someone who tends to get angry fast.

Also, if you review some one-line-change (or even a on-character-change), adding a 👍 suits most of the time.

Check the scope of the change

Can the change be described with one simple task? Or are several changes packed into one review? The review should always contain only one taks at time. While this can be sometimes difficult to define, it is often easier to determine, if some completely non-relating tasks have been done together. Also, if the change is really big and spreads across several hundered lines, you should consider, suggesting to split it up into two or more smaller changes.

Try the changes in your environment

This is often optional, but most of the time I try the changes out locally in my environment, even if it passes CI. In our team, everyone has a slightly different environment, which means especially changes at build and environmental scripts can cause problems for someone else. I want to make sure that the changes work for everyone in my team.

Check for changes that affect the ecosystem around your project

If there are any changes, that might affect other software around your project, you and co-developers should make sure, they are documented and clearly communicated. This is particularly important, if the review contains breaking changes.

Don't fight about details

As long as those details don't introduce some new problems, you should not spend too much time and effort in difficult emotional discussion. The importance of positive mood in teams is often underestimated.

🤷‍♂️ What else?

For me, there is always one important thumb rule, that is always true and helpful: Reviews are not about you, they are about the code. Don't take things personally! Instead, try to stay calm and take a short break if something happens during a code review, that has the potential for personal conflicts.

Surely, there is more to look at in a code review. But these few tips helped me in the past to get a positive output from most of the reviews I have done by myself or where I helped others to do a great review. Hopefully they will do it for you too.

One last thing I'd like to share: If possible, automate as much as you can of your code review process. This will save you a lot of time. The most basic things can be integrated in every CI pipeline. For this I highly recommend to have a look at code style linters or tools like danger.

If you have any additonal and helpful tips for code reviews, I would be very happy to hear them.