How to nitpick on code reviews with empathy
You’re reviewing a Pull Request. You see a variable that should be renamed. Or a comment that should be rephrased. Or some if/else logic that could be a guard clause.
Should you comment on the PR, or let it go?
My answer: in most cases, yes, you should leave a comment. Minor, incremental improvements do wonders to control the complexity of a growing code base.
Leaving minor comments on code reviews is commonly referred to as nitpicking. It’s important to nitpick — but most reviewers don’t do it right. They’re lazy. They don’t add context or reasons. They don’t take the time to reduce cycles and grow their peers.
Each code review comment is an opportunity. A good comment can build your credibility and strengthen your relationship with the author. A bad comment can cause the author to resent you.
And yes, even a nitpick is an opportunity. Here’s how to nitpick on code reviews:
Prefix with “Nit:”
This affirms that the comment is a minor piece of feedback. The PR author is less likely to get defensive. They’re more likely to receive your comment with an open mind, and implement it without reservations.
Give a recommendation, not a command.
Nitpicks are always subjective. They’re a matter of personal preference. The language should indicate that you acknowledgment this.
Give a clear suggestion, in code.
GitHub makes it easy to make a clear, suggested change — use it.
If the nitpick is your only comment, approve the PR.
Don’t block unnecessarily. This saves both yourself and the author a cycle, so you can ship the PR faster. Trust that the author will address your comment before they merge the PR.
Here’s the anatomy of a good nitpick:
The above nitpick:
- ✅ Prefixes with “Nit:”
- ✅ Gives a recommendation
- ✅ Gives a reason why
- ✅ Gives a clear suggestion, in code
- ✅ Is non-blocking (the PR is approved)
An author receiving this comment is very likely to implement the nitpick, without reservations. They’re also likely to learn something new — they can leverage this knowledge on future PRs. (In this example, the context you can’t see is that the suggested change more closely matches the function naming conventions within the code base).
Once you start nitpicking like this, you’ll never go back.
Your teammates will see that you’re investing time and effort into their growth. You’ll build some credibility, and you’ll create a healthier team environment.
Whenever you’re performing a code review, you want to have high standards. You want to nitpick.
But don’t lose sight of the bigger picture. There’s a human on the other side of your comment. Grow your peers, and build relationships. 🔑
Like this article?
Check out my video course — Master the Code Review! Licenses are available for individuals and teams. 🎥
