A Simple Strategy for Happier Code Reviews
Code reviews are a key way to maintain quality in a codebase and provide developers with high-impact touchpoints to share feedback and knowledge. While not as hands-on as a pair programming exercise, they should be a positive and useful experience for both parties.
Intrinsic to code reviews is granular scrutinisation of work, which if mishandled has the potential to feel invasive or even discouraging for team members of any level. For instance, a small comment on a line of code delivered without the tone intended face-to-face might instead be received as a sharp criticism. Other times, it might be unclear whether one should act on a piece of feedback.
Here, I share a small framework which can help code reviewers stay mindful, unambiguous, and concise.
Be visual: Code review badges
What do I as a reviewer want the outcome to be from this comment?
The above question above led me to introduce code review badges. These provide clear visual signalling that make reviews faster to author and faster to interpret.
I've found that these have been enough to categorise almost every situation and are easily interpretable. When rolling this out, feedback from peers was immediate and positive.
- Comment This note is explicitly a comment, such as a compliment or point of interest. There is no action to take.
- Development practice There’s a change you should make here, but it’s not to do with your implementation.
- Recommendation There’s a change you could make here. It’s okay if you disagree or don’t have time to do it now; it is up to you if you want to take action.
- Hard recommendation It’s important that you address this feedback. It has significant functional or design implications.
Above, I've used the shields.io service to create custom SVG badges. You can create and customise yours as needed by following the URL pattern.
Be balanced: Some pointers for feedback
With the above in place, I like to remember the following tips when writing a review.
- Add one badge to every review comment.
- Explicitly give a shoutout on something good.
- When recommending a change, try to give justification (and ideally, a reference).
- For longer explanations: is it worth writing a paragraph about this thing? Outline your comment, then add that you're happy to take a quick break together to talk it out.
- Encourage people to file tasks, where feedback isn't blocking, in order to follow up later.
- Remember that giving a small pointer is often enough for people to figure out the necessary change by themselves. Be mindful that they will have spent more time with the problem than you!
Buddy up!
Remember that if feedback is substantial enough, it's worth reaching out in person.
Further to this, there are cases where we want to invest time up front to avoid unnecessary feedback loops in code review. Unfortunately, we don’t always have the resource to pair program on a task. Here I recommend shifting left to paired design planning. This is great in cases where a person may need more support, or they are tackling an important part of the system. Time spent here disambiguating the problem means you're on the same page during review, and should therefore recoup time overall.