The code review is simply one of the best software development practices. It provides many benefits, such as finding bugs, improving the quality, and sharing the knowledge throughout the team.
Performing code reviews isn’t straightforward, though. As a reviewer, you need to put yourself in the author’s shoes by understanding the context, how things work, and the purpose of the changes introduced and then following the technical solution.
You may need to do even more than the author, like finding bugs, searching for alternative solutions, and comparing them. Coming up with a solution is one thing; seeking out more and comparing is another.
The difficulties of code review aren’t limited to only technical reasons. A code review involves communication between multiple persons, emphasizing the need for critical thinking.
And most humans don’t do well when it comes to coping with criticism. Therefore code review becomes a slippery slope. A comment can either ruin or brighten the day of the author. In this article, I want to list six tips that help establish a delightful code-review experience for both the author and the reviewer.
1. Use Emojis
Code reviews are often an asynchronous, textual communication process. But some aspects of communication, such as emotions and intentions, are often lost while writing. To cope with that, we use emojis in our daily lives, such as when chatting or tweeting. So why not use them for code reviews?
Here’s the emojis we use in our team. A Christmas tree(🎄) means the requested change is subjective and optional, such as personal preferences over variable names. More Christmas trees (🎄🎄) say that the comment is more subjective, and the author can omit them. We use an owl when we want to learn more about a change rather than interrogating: “🦉Why are you using this library here?” We scream (😱) when we notice silly mistakes, such as typos. We clap hands (👏) for the changes we like. And finally, when we complete the review, we celebrate it with 🍻.
We also use ad-hoc emojis to convey our intentions in a better way:
“I don’t think this line is correct. Are you sure that it works?”
I don’t think this line is correct. 🤔 Are you sure that it works?
It’s not easy to figure out the emotion in the first comment. The author can interpret it as rude or questioning, which can put him/her into a defensive position. But what you want from the author is to investigate and justify the functionality of the commented line. The second comment sets up a curious intention by just adding an emoji to the same sentence.
2. Comment Humbly
Submitting code changes for review can be stressful because someone else will inspect the author’s work to critique it. Developers tend to own the code they write, which can cause the feedback to be taken personally, causing stress. There’s a simple solution to avoid this: Comment with a humble attitude. Below are two variations of input for the same line:
Comment 1: “This is ugly! Why did you use an abstract class here? There’s no need to use it. You should use an interface instead.”
Comment 2: “Is there a specific reason that we use an abstract class here? Using an interface here might be better since there aren’t any default implementations, and it doesn’t extend from any other class.”
Can you spot the differences that make the second comment a better one? Let’s take a look:
Take responsibility for changes as a team
The first comment uses a you-statement. But the second comment uses a we-statement, emphasizing that everyone in a team owns the code and is responsible for the changes, even if one member writes it.
Focus on the code, not on the author
The first comment accuses the author of the change, which puts them in a defensive position. That’s not a good start for improving the code quality.
The second comment doesn’t make it personal. It states that there’s an abstract class, which is the main focus of the feedback. It also provides technical arguments for choosing interfaces, which helps with keeping the conversation about the code.
Don’t jump to the conclusion
The first comment immediately settles that an interface is better than an abstract class. On the other hand, the second comment doesn’t directly make a judgment. Instead, it challenges the author to compare the two alternatives. Who knows, maybe they have a valid reason to justify it.
In summary, the first comment sabotages the communication and converts the review process to an unpleasant experience. In contrast, the second comment is opening up the collaboration.
3. Review to Appreciate
Everyone likes a little appreciation for good work, and developers are no exception to this rule. Appreciating beautiful, clean code is an incredible tool at the hands of an experienced reviewer. Because with appreciation, a code review is no longer one-way, criticism-only feedback.
Recognition increases the author’s morale, reduces stress, and motivates the author to process the input that requires changes to the code. The author will feel more comfortable when submitting a changeset for review in the future.
4. Group Similar Comments Together
It’s not helpful to post a comment for a similar mistake many times. It’s discouraging and can slow down the review tools. Each comment can also cause automatic emails to be sent to the author and other subscribers, which might quickly get disturbing.
Instead, you can consolidate them in a single comment, such as: “Typo in the object (multiple places).”
5. Discuss Disagreements in Person
When there’s a disagreement that seems to take longer to resolve during a code review, the best action is to discuss the matter face to face with the author. Addressing issues in person saves both the reviewer and the author from unnecessary bickering, which causes stress and takes up time.
Invite your team’s tech lead to the face-to-face meeting as a tiebreaker if you and the author agree to disagree.
6. Accept That You Don’t Write the Best Code
We software developers take great pride in the work we do. We love and own the code we write. We also want others to like our code as well.
But this shouldn’t restrain you from having an open mind toward criticism. Your approach may not be the best one for the task, or it can have bugs. The whole goal of code review is to make the code — and thus the product — better. That’s the most crucial goal of the team.
So there’s no need to take feedback personally at all. The best code is the one that each team member contributes, understands, and owns at the same level.
Thanks for reading! I hope these are helpful to help you ace your next code review.
Top comments (0)