Code Reviews with Empathy
Code reviews are a daily task for most developers. The primary goal of a code review is to ensure that code getting merged into a codebase is bug-free and meets the standards of the code owners. While straightforward in purpose, the execution of a good code review is often hard to pin down. In a perfect world, we would request fixes for objectively “bad” code, and approve the objectively “good”, with no room for disagreement. In reality, much of what comes up in code reviews falls within the grey area of opinion and preference, which can easily lead to ineffective disagreements if not handled with care.
Why is Empathy Important for Code Reviews?
Us developers are humans with feelings and egos, and when we are feeling attacked, our egos spring into action. When our code reviews ignore this fact, they can result in trivial arguments and resistance toward other opinions , which is obviously counterproductive. When we write code reviews with empathy and respect for the human on the receiving end, we avoid putting our teammates on the defensive, and we begin to foster a culture of collaboration, openness, and growth.
Let’s walk through some examples of the kinds of feedback we often give during code reviews, and examine how we can integrate some empathy into this feedback.
Scenario 1: Objectively Bad Code
Guidelines for reviews of bad code:
- Provide enough information about the issue to give your teammate a jumping off point for resolving it.
- Assume that your teammate is capable, and avoid explaining fundamental concepts.
Examples
Bad Example 1: This review doesn’t provide any information at all.
Bad Example 2: This review over-explains and comes across as condescending.
Good Example: This review provides enough useful information to resolve the mistake without assuming the code author is clueless:
Scenario 2: Confusing Code
Guidelines for reviewing confusing code:
- Avoid asking for clarification as a means of challenging code you don’t like.
- Make it clear that there is a hole in your knowledge — not that the code author did something wrong.
- Pinpoint the source of your confusion.
Examples
Bad Example 1: This review comes across as demanding, and puts the code author on the defensive to explain themselves.
Good example: This review specifies what part of the code is unclear, and signals to the code author an openness toward understanding their solution.
Scenario 3: Differing Preferences*
*Before code even gets to the review stage, teams should use agreed upon style guides and linters to handle differences in preference, and should have conversations about major rules, such as file structure. If this process is done well, most matters of preference discussed in code reviews should be fairly minor.
Differences in preference are by far the most difficult aspect of code reviews to do well, because each developer’s ego is at stake (or so it often seems). Since code reviews don’t happen face to face, tone can be misinterpreted as hostile, and developers can go on the defensive very quickly. This often spirals into unproductive bikeshedding, and is very ineffective to the goal of the code review.
The best way to avoid unproductive back-and-forths over matters of opinion is to avoid them entirely. If an aspect of your teammate’s code works and is easy to understand, but doesn’t meet your preference in some way, consider leaving it be. For most matters, it’s more effective to propose your preference to all of the developers on your team in a dedicated forum, and come to a team agreement on the matter separate from the code review.
If your preference is something that you believe improves the code in a meaningful way, it is appropriate to raise it in the code review.
Guidelines for reviewing Matters of Preference:
- Keep in mind that the code author is not obligated to change their code if it doesn’t violate the team’s style guide and doesn’t introduce weaknesses into the codebase
- Do not hold their PR hostage based on a matter of opinion.
- Make clear that the request is based on opinion
- Explain the reasoning behind the opinion
- Make clear that you respect the final decision of the code owner with regard to accepting or rejecting your opinion.
Examples
Bad Example 1: This review implies that your opinion is a fact, which it isn’t.
Bad Example 2: Though better than Bad Example 1, this review doesn’t provide any reasoning behind your preference to help the code author decide whether they agree.
Good Example: This review makes clear that the request is a matter of opinion, explains the opinion, and opens up a forum for discussion.
TLDR
Most of our conversations about code happen during code reviews. Writing code reviews with empathy goes a long way toward fostering a culture of openness to learning and improvement. This enables us to have productive conversations about best practices, to write great code from the start, and to deliver our work with fewer bugs in less time.
