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