How to Communicate Effectively as a Code Reviewer

Nowadays, most software companies rely on code reviews to ensure code quality. As a result, software engineers spend a significant amount of time communicating with peers through comments on GitHub Pull Requests or GitLab Merge Requests. Knowing how to communicate effectively in these contexts can make a significant difference in the quality of the code and the relationships within the team.

Here are four tips to help you become a better code reviewer.

1. Don’t Talk to the Author, Talk to the Code

The goal of a code review is not to criticize the author but to improve the code. Besides, it’s entirely possible that your perspective is incorrect. To foster collaboration and avoid creating tension, refrain from using imperative language like, “This is ugly, you should build this list using a list comprehension.” Instead, say something like, “This list could be built using a list comprehension for better readability.”

By framing comments this way, you refer to the code as a shared responsibility of the team. The goal is to improve the code together, not to make your colleague feel bad.

2. Categorize Your Comments

Comments in a code review can address a wide variety of topics: bugs, readability improvements, performance concerns, architecture questions, or even praise. In a large merge request with dozens of comments, categorizing them can be incredibly helpful for the author.

You can achieve this by prefixing your comments with labels like bug:, perf:, or praise:. If you prefer something more visual, you could use emojis, like those suggested by Gitmoji. Categorizing comments makes it easier for the author to quickly understand the nature of your feedback.

3. Prioritize Your Comments

Not all comments carry the same weight. Some issues are critical (like functional or security bugs), while others are less so (such as code organization). It’s important for both the reviewer and the author to understand the difference.

To help the author prioritize effectively, be clear about which comments are essential and which are not. Adding (optional) to certain comments can emphasize that they are suggestions rather than requirements. Additionally, if your only comments are optional, consider approving the merge request. This signals that the author is free to decide whether or not to address those suggestions based on time constraints or other factors.

4. Provide Concrete Suggestions

Commenting on potential improvements is great, but vague feedback can be frustrating. If you have a specific change in mind, take the extra step to rewrite the line of code as you envision it. By providing an exact suggestion, you save the author the guesswork of interpreting your feedback. Plus, in the process, you might discover that your idea isn’t feasible or could be improved upon even more — collaboration is key!

Conclusion

Effective code reviews are not just about catching bugs; they’re about communicating clearly, fostering a collaborative atmosphere, and helping the team grow together. When you frame your comments thoughtfully, categorize and prioritize them, and offer specific suggestions, you contribute to the shared ownership of the codebase and the success of your team.

Remember, every code review is a chance not just to improve the code, but to strengthen the bonds between teammates. Communicating with empathy and precision is what sets apart a good reviewer from a great one.