Constructive Code Reviews

2019-12-21

These are some guidelines for code reviews that I like to follow. Hopefully this will be a list that I keep refining and adding to as I gain more experience.

The key to a code review, and this really applies to all kinds of online communication, is to remember that there is a human behind the screen. It is easy to forget this; an e-mail pops in your inbox, and there it is, the code review. Just in an instant, out of nowhere. But this sense of speed is false, a product of machines, and not representative of all the human effort that went into that work.

Humans have lives, emotions, and problems of their own. Some are stressed, others lack self-confidence. For some, it is their first job. Others have been there for a while, but have lost a sense of direction. Whatever the situation, being cognizant of all these feelings humans have is key to a humane code review. So remember: there is a human on the other end, and we want to tailor our words to leave a positive impact on them, for the betterment of themselves as well as ourselves.

Guidelines

Positive grammar

Structure the grammar to leave a positive connotation. In a compound sentence, typically the thing I remember more strongly is the last clause, because that is the last thing I read. Therefore, I make this last clause the positive one.

For example, suppose that someone tried to fix the car, but the car remains broken despite their attempts to fix it. We might say something like:

You tried to fix the car, but it's still broken.

The car is still broken, although you tried to fix it.

The fact is the same, the difference is in connotation. In the first sentence, the thing I will remember the most is "it's still broken", which has a negative connotation and seems to punish the person for not fixing the car. In the second sentence, the last and more memorable clause is "although you tried to fix it", which has a more positive connotation and recognizes the person for their effort in at least trying to tackle the problem. Make the positive clause the last one.

Generally, try changing your grammar to leave a positive connotation.

Propose alternatives

Don't just say you don't like something. It's kind of moronic, and it also doesn't add anything. For everything you are not entirely happy with, try to propose a better alternative. This is possible most of the times. Other times, the problem might be truly complex and we are unable to think of a solution during the code review. In that case, explicitly state that you tried to find an alternative and could not come up with one, and maybe suggest a follow-up discussion; don't just leave it open-ended.

Find something positive

What are the chances that you do not like anything in the code for review? Very low. Therefore, always find something that you think is a good change, and let the other person know. Adding a non-actionable comment on the review might seem a little annoying, but it is only a minor annoyance compared to the sense of appreciation the other person will get from your comment.

Reserving "I"

I tend to avoid "I" and use "we" instead. "We" seems to reinforce the sense of teamwork, as in "we" are working on this solution together. If I use "I", it is only in the rare case where I want to express a personal opinion but do not mean to suggest that anything should be done about it, like when describing my own coding preferences, for example. And this really should be a rare case; going around giving non-actionable opinions in code reviews is kind of moronic. Focus on the actionable and on the improvement, not on your narcissistic tendencies.

Be thankful

It might take you 20-30 minutes to review the code. It might have taken the other person several hours or even days to write it. This is especially true of simple ideas, which tend to be expressed succinctly and are not representative of all the work that went behind them. So be thankful for the other person's effort, and explicitly recognize it by saying thanks. This can be done in individual comments of the review or in the general comments section.

Do not go on defense

We, the code reviewers, are humans too, and we may be offended by the way someone expresses themselves in response to our feedback. Do not go on defense. Chances are, the other person does not have the same writing skills and communication awareness that you do. This is especially true if the language used is not their first language, which will happen very often. Flip the false offense around and respond constructively. If possible, meet the other person in real life to convince yourself that the offense is false and just a product of online communication.