My favorite code review tips

3 minute read

Code review is part of most programmers’ job, and involves a number of written interactions with your colleagues over Github. I found this blog post “How to Do Code Reviews Like a Human” particular helpful to be “a nice guy” in a code review.

Photo by Jason Richard on Unsplash
Photo by Jason Richard on Unsplash


  • Treat code reviews as a highest priority.
    • The absolute maximum turnaround on a code review should be one business day. If you cannot make it, let your teammate know.
  • Each review should be maximum 20-50 notes, and start with a high-level feedback rather than details.
  • Do the suggestions at once rather than sending multiple suggestions.


  • Never say ‘you’.
    • Be clear that you’re critiquing the code, not the coder.
    • Replace ‘you’ with ‘we’.
  • Omit the subject from the sentence, like “suggest renaming…”, or use passive voice, or questions “what about” or “how about”.
  • Frame feedback as requests, not commands.


  • Explain both your suggested change and the reason for the change (ideally with an example).
  • If you can’t articulate exactly what is wrong with a piece of code, explain what you can, but keep it objective.
    • If you say, “I found this hard to understand”, that’s at least an objective statement, as opposed to “this is confusing”.
  • Provide supporting evidence where possible in the form of links. The farther you stray from authoritative documentation, the shakier your evidence becomes.
  • When you notice that several mistakes fit the same pattern, don’t flag every single instance.

Scope of PR

  • Respect the scope of the review.
  • If the change doesn’t touch the line, it is out of scope.
  • If you have a weak suggestion, say “optional”.
  • For more than 400 lines, ask them to split it into smaller pieces.
  • Refuse to review any change for more than 1000 lines. Ease their burden of splitting by identifying logical boundaries fro the split.

Be Nice

  • Offer sincere praise.
    • “I wasn’t aware of this API. That’s really useful!”
    • “This is an elegant solution. I never would have thought of that.”
    • “Breaking up this function was a great idea. It’s so much simpler now.”
  • Grant approval when remaining fixes are trivial, such as minor comments or optional suggestions.


  • Handle stalemates proactively.
    • If possible, avoid sending each other code reviews for a few weeks until things cool down. Instead, meet in person or over video chat, and discuss rather than continue over a PR.
    • Are you arguing about things that should have been covered during the design review?
    • Messy review arguments tend to be less about the code and more about the relationship between the people involved.
    • If the situation is getting worse, discuss the situation with your manager.

Subscribe to my blog

* indicates required
Thank you for reading my blog post! If you liked it, please subscribe to receive new posts. I won't give your address to anyone else, won't send you any spam, and you can unsubscribe at any time.