Published April 29, 2021
Advice to make code reviews easier: A short guide with tips and tricks for providing constructive code review feedback politely.
Code reviews are a necessary evil of being part of a software development team. As a first quality assurance hurdle, their purpose is to check that your coworker’s code is up to snuff and conforms to your team’s standards. That can mean many things: Is it functional? Is it efficient? Is it correctly formatted?
By virtue of pointing out potential flaws in others’ work, code reviews are often taken personally. Some programmers feel attacked by comments criticizing their work when, in reality, you’re all on the same team trying to build something amazing. Here are a few things you, the reviewer, can do to reduce the chances of your comments being misinterpreted, thereby helping to maintain a good social climate within your team.
Instead of pointing out a possible flaw in someone’s code, consider stating it as a question. The chances are all that’s needed is an extra comment explaining why it was implemented in that particular way. If that’s not the case, asking a question gives the author an opening for explaining their own shortcoming, thus encouraging them to think about a better solution and correcting their previous thought process. The best way to learn, as they say, is to teach.
This method also avoids any conflict of authority. The author wrote the code and is probably more immersed in its details than the reviewer. By asking a question rather than flatly stating an error, you acknowledge that your intuition might be wrong and that the author, being the expert, should explain why their code is, in fact, good.
This is maybe the most important point on this list. Everyone wants to be recognized for a job well done. When reviewing code, programmers tend to only focus on the negative. This can be very frustrating for the author, especially if their code is an innovative solution to a complex problem. It doesn’t take much to insert a “Nice!” here and there — positive comments go a long way towards making the author feel appreciated. Furthermore, after a code review session, you can leave a summary comment with your findings, including the good and the bad. By acknowledging your coworker’s successes, you make them more comfortable with admitting, fixing, and learning from their failures.
Writing comments in a polite, professional manner should be the obvious thing to do. Maybe there’s a blatant error that could cause serious harm, in which case stating your comment as a question is not a good idea. But before writing something that might sound rash and could be taken personally, think about their current situation for a moment. Do you know them to be a person who would not usually miss such a crucial error? If so, what might have caused them to do so here? Are they going through something that might cause them to lose focus?
You might think that’s taking it too far, but as much as everyone tries to be their best, most professional selves, we’re all still only human. The person in the mirror is, despite everything, still you. Not everyone can separate their personal and professional lives completely, so try to be aware of that when reviewing someone else’s work.
Another good way to provide constructive feedback is to simply go talk to your coworker (either in person, if you’re in the same office, or via a video call, if you’re working remotely). This gives you a chance to socialize, smooth over potentially unpleasant conversations, and let them know it’s all right to make mistakes. Posting your comment on the review could make the author feel called out, as their error has been put out in the open for all to see. By bringing the issue up in person, you’re allowing them to uphold their reputation — if that’s what they’re worried about.
Instead of pointing fingers, suggest potential fixes and improvements. This is a good way to show you’ve actually engaged with the author’s code and not just glanced over it. Supplying suggestions can make your coworker’s life easier, especially if your VCS supports directly applying those suggestions to the code. It shows you’re not just there to make them feel miserable but are working towards the same goal of keeping the quality of your code-base as high as possible.
Check whether a set of issues is crucial and definitely in need of change or not. If it isn’t, you can accept the PR with a small closing message like “LGTM, just a few suggestions. Merge when ready.” This puts responsibility for those issues onto the author and allows them to take ownership of their own work. By encouraging changes after you’ve accepted the pull request you’re also demonstrating that you trust them to make the right choices. People will appreciate having the final say in something they put together — whenever you can, give it to them.
Powered by Froala Editor