10 Commandments of Code Review

Programming is a social activity. We work with other people, not in a vacuum. We share code with other people. We share ownership of code with other people. We share responsibility for code with other people. The sharing goes the other way as well. Others share their use cases, their requirements, and their experiences. One of the places where all of that comes together is in a code review.

In some cases, such as pair or mob programming, code review is a synchronous, ongoing activity, but that’s not what I’m going to talk about now. For most us, code review is an asynchronous event. Someone changes some code, throws it over a wall for review, then waits, more or less patiently, for a response. Eventually some sort of agreement is reached, and the code gets merged into the codebase. I have a lot of issues with the whole “throw it over the wall” approach, which is another thing to talk about at a later time. Meanwhile, here are 10 important things to keep in mind when writing or reviewing a code review.

1. Thou shalt treat a code review request as an important task. Of course, you should give a thorough review when you give one, but there’s more to considering it important than that. It means declining quickly if you know you’re not going to be able to do the review. It means not putting it off for days. Different teams have different benchmarks, but 1 working day is a good rule of thumb.

2. Thou shalt create code reviews knowing that others will read them. As I said earlier, always review your code review before sharing it. Make sure it has what it needs for the reviewer. The right files. The right explanation of why the change is being made. A description of the change that someone who didn’t make the change can understand. A list of tests to validate the change.

3. Thou shalt not take comments personally. When reading comments on your review, remember, the comments are about the code, not you the author. Don’t get angry and ignore the comments. Take them seriously. Be willing to accept feedback and be willing to push back if you have a well thought out reasons. Nor shalt they make comments personal. Comment on the code, not the author.

4. Thou shalt keep your review to a single topic. A code review should be about a single logical change. If you find you need to keep using and in your description, consider splitting the code review into multiple reviews.

5. Thou shalt consider all feedback. Not just consider and ignore, but consider and respond. The response might be changing the code, it might be an explanation of why you’re not changing the code, or it might be agreement and a promise of a follow-on change.

6. Thou shalt say why. Whether it’s the code review description, a code review comment, or a reply to a comment, always explain yourself. It can be as simple as “I agree” if there’s no disagreement, but “No” is not acceptable, “No because …” can be.

7. Thou shalt not be absolutist. Writer or reviewer, be willing to compromise. Is good to have a strong opinion. It’s good to explain yourself. Like with everything else development, the right solution for a specific review depends on the context. Be willing to listen to the other people and work together to come up with a solution you all can more forward with. Again, remember that it’s OK to say there is more work to come, either right away or later when you know more about the situation.

8. Thou shalt not argue with the style guide. One thing I like about Go is that most of the style guide is built into the language and there aren’t any options. The writer and the review might not agree with it, but it is what it is, and we all go with it. For other languages you might have more choices, but the review is not the place to argue them. If you need to argue about the style guide, do it outside the review.

9. Thou shalt remember review feedback. The first time you receive some feedback it’s a learning experience. The second time you get the same feedback it’s helping you build a habit. If you get the same feedback a third or fourth time, stop for a minute and think about why. Understand where the feedback is coming from and incorporate the learning into your future reviews. If you’re not learning from your reviews, you’re being disrespectful to your reviewers.

10. Though shalt treat your review partners as you want to be treated. Just like that other golden rule, whether you’re the writer or reviewer, think about how your partner will feel. Think about how you would feel if you were on the other side of the equation. Then act the way you would want yourself to act.

Code reviews, regardless of which side you’re on, are there to help produce the most value you can. But they can be so much more. They can be teaching and learning tools. They can be vehicles for sharing. They can be a gift that you give to yourself and that teams give to themselves.

If you let them. So take advantage of your opportunities when you can.