My favorite code review tips

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

Timeline

• 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.

Grammar

• 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.

Feedback

• 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.

Conflict

• 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

Email Address *

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.