Code Review Etiquette. Keeping Peer Review Classy
By: Mariel Grace
Tags: Technology, Software Development, Github, Programming, Code Review

Code Review Etiquette

The Do’s and Don’ts of Peer Review

Photo by John Schnobrich on Unsplash

When I hear the word “etiquette”, it brings to mind images of perfectly set dinner tables and the knowledge of the proper fork to use during every course of a meal. So, when I found out that there was a certain etiquette that goes along with reviewing code, I was confused to say the least. After learning to code and getting my first job as a programmer, I still had to go to some type of finishing school?! Not quite.

In this article, we will discuss code review etiquette, a.k.a. the social norms involved with making a pull request and reviewing others’ pull requests. So, sit up straight and get your pinkies up, because we are about to get downright polite.

Why is code review etiquette important? Etiquette is important for several reasons, one of them being that if you don’t abide by it, no one else will enjoy being around you.

With code review, not following etiquette means that people will not enjoy reviewing your code, sending code your way for reviewal, or both.

Code reviews are vitally important to the health and strength of your code. They also contribute to your overall development as a programmer. If you learn to code review properly and do it well, you will improve your code leaps and bounds. These benefits apply beyond the individual coder, and to the team and company at large. When everyone performs good code reviews, the team and the company prosper.

There’s actually two types of etiquette when it comes to code review: the one from the coder and the one from the reviewer.

A code review is a critique and a critique can often feel more personal than the code writing itself. A sloppy, under-researched, or insensitive code critique can cause difficulties between team members, reduce overall team productivity, and diminish code quality over time.

The code

Imagine you are dining at a fancy restaurant. There are certain rules and social norms you expect. You expect the waiter to look polished and clean, polite and helpful, and you expect them to give you a menu and remember your order. It is all toward the purpose of making the diner’s experience more pleasurable and predictable. Like the waiter, the person writing the code should have in mind that it will be reviewed by a human being and as such should try and make that person’s job easier.

Code Clean

Someone is going to read what you write, so the least you can do is not make their job any harder. This means, not using any weird or irrelevant variable names. It also means making your code less complex. If you have a tendency to try and be clever with your code, don’t. It only makes the job of your reviewer and the programmers who come after you much harder.

Self Review

Make sure to read your own code before submitting it for review; make sure it does what it’s supposed to do and try to run some static analysis on it to clean up any possible problems.

Explain yourself

Most comments are either meaningless or a sign that the code could be improved, but do leave a comment explaining your algorithm or your reasoning if it took you some thought to get to your conclusions; also, fill in the description for the Pull Request, or leave a comment there if you feel that something else deserves an explanation.

Don’t take it personally

Don’t take the comments from the reviewer personally. You are not your code. If someone attacks the code, don’t make them enemy #1. Instead, work through the code with them to understand their reasoning; agree or disagree, but treat the code as an object, and not as an extension of yourself.

The review

Let’s go back to our fancy restaurant. The waiter serving you that evening is still new, and learning the ropes of the restaurant so they make a couple mistakes over the course of the night. You don’t mind that the waiter forgot a drink that you ordered, but your date berates them with insults. This does not follow in line with etiquette of a nice restaurant, nor does it help the new waiter improve. The reviewer is like the diner. They should have in mind that the person who wrote the code (or the waiter) is a human being and, as all human beings, has flaws and feelings, and those should be taken into consideration when commenting code during reviews.

Comment the code, not the coder

Without realizing it, engineers can neglect the difference between insightful critique and criticism because of adding personal relationships into the review. The focus of the code review is the code, and not its creator, so watch the way you address any issue.

Try to refrain from expressions such as:

“you should return out of this function early”

“we should return out of this function early”

Replace them with:

“return out of this function early”

Notice how the amount of text needed to communicate the same thing without using personal references takes fewer words and has greater clarity. This helps with human interaction, separates code discussion from personal discussion, and fewer words are needed to communicate the same idea.

Explain, don’t complain

If the same person makes the same mistake over and over again, explaining and not complaining might be difficult to manage, but the truth is that it is much more effective to say “there is a better way to do this”, and to show them the path, than it is to say “this is really wrong”, especially if you believe that it is truly wrong. Both statements get the basic message across, but the second statement challenges the person who wrote the code to defend it. When explaining that there might be a better way to write particular code, it can be helpful to provide sample code or an informational article to point them in the right direction.

Don’t let things escalate

If you find that you are exchanging many comments on a code review, and things seem to be escalating, try to have a conversation in person instead. Do it as soon as possible. Another way to avoid escalation is to remove passion indicators, such as exclamation points, from your comments. Instead of “yelling” at them what they did wrong, present the side effects of their code and ask how they might improve it. By changing your passionate statement to an informative question, you are allowing them to grow as a coder and explore new fixes.

You do not want to be the bad waiter, nor the rude customer in our programming restaurant. If you take these etiquette tips and apply them to your code review flow, your future self and your current teammates will thank you for it. Remember that code reviews are meant to improve code and avoid costly errors. Take your ego out of the code and always keep your pinkies up.