/ReviewGoodPractices

A list of good practices for giving good reviews in PullRequests

1) Don’t focus on style

Agree on a consistent style guide and let formatters do the checking. Style is subjective and does not bring value if it is not consistent. Agreeing on a style guide and using formatters to check for consistency ensures that code reviews are focused on the code's functionality and purpose rather than its style.

2) Offer examples

Instead of instructing the author what to do, provide specific examples or even code. Providing examples helps to avoid misunderstandings and makes it easier to understand, accept and implement the requested changes.

3) Don’t use ‘you’

Word your feedback in a way that minimizes the risk of raising your teammate’s defenses. Be clear that you’re critiquing the code, not the coder. Using ‘you’ increases the risk that they’ll take your criticism personally. Consider using ‘we’ as it stresses the shared code-ownership.

4) Frame feedback as requests, not commands

Requests make it easier for the author to push back politely. They may have a good reason for their choice. If you frame your feedback as a command, any pushback from the author comes across as disobedience. If you frame your feedback as a request or a question, the author can simply answer you.

5) Tie notes to principles, not opinions

Explain both your suggested change and the reason for the change. Grounding your notes on principles frames the discussion in a constructive way. Provide supporting evidence where possible in the form of links, so the author can learn more about the principle if unfamilar with it.

6) Make the code better, not perfect

Although you might want to explore every opportunity to improve the code, the author’s patience is finite and might be overwhelmed. They might grow frustrated if you withhold approval for too long, because you keep thinking of new ways to improve the code, it slows down the process and usually is not a good enough investment of your resources. Focus on the important things. See Parkinson's law of triviality.

7) Respect the scope

In order to keep reviews and changes small, don’t review code that is out of scope of this change. Grant approval as soon as possible. Don’t withhold your approval if there are only minor changes left and trust that the author will consider your feedback and work it in if they agree with it. Don’t be the last cruel gatekeeper who upholds code quality as there will be situations when you can’t be there or others will do the review.

8) Be inclusive

Use full sentences to express your suggestions and provide necessary details and context. This is more respectful and doing so allows others to join the discussion easily and better understand your arguments. This allows them to make informed decisions.

9) Be specific

Instead of asking open or unbounded changes like “Add more tests”, elaborate on what exactly can be improved or is missing so the author does not need to guess and avoid doing the wrong. Ideally offer examples (See above).

10) Don't nitpick

Invest author's and reviewers's resources on issues worth solving. This prevents frustration and allows you to deliver value sooner. If you feel something is worth changing, don't reduce your feedback by adding something like "nitpick".