Code Review Guidelines

As a Reviewer or Author

DO: Assume competence.

An author’s implementation or a reviewer’s recommendation may be due to the other party having different context than you. Start by asking questions to gain understanding.

DO: Provide rationale or context

Such as a best practices document, a style guide, or a design document. This can help others understand your decision or provide mentorship.

DO: Consider how comments may be interpreted.

Be mindful of the differing ways hyperbole, jokes, and emojis may be perceived.

e.g.:

Authors Don’t Authors Do
I prefer short names so I’d rather not change this. Unless you make me? :) Best practice suggests omitting obvious/generic terms. I’m not sure how to reconcile that advice with this request.

DON’T: Criticize the person.

Instead, discuss the code. Even the perception that a comment is about a person (e.g., due to using “you” or “your”) distracts from the goal of improving the code.

e.g.:

Reviewers Don’t Reviewers Do
Why are you using this approach? You’re adding unnecessary complexity. This concurrency model appears to be adding complexity to the system without any visible performance benefit.

DON’T: Use harsh language.

Code review comments with a negative tone are less likely to be useful. For example, prior research found very negative comments were considered useful by authors 57% of the time, while more-neutral comments were useful 79% of the time.

As a Reviewer

DO: Provide specific and actionable feedback.

If you don’t have specific advice, sometimes it’s helpful to ask for clarification on why the author made a decision.

e.g.:

Reviewers Don’t Reviewers Do
I don’t understand this. If this is an optimization, can you please add comments?

DO: Clearly mark nitpicks and optional comments.

By using prefixes such as ‘Nit’ or ‘Optional’. This allows the author to better gauge the reviewer’s expectations.

As an Author

DO: Clarify code or reply to the reviewer’s comment.

In response to feedback, failing to do so can signal a lack of receptiveness to implementing improvements to the code.

e.g.

Authors Don’t Authors Do
That makes sense in some cases butnot here. I added a comment about why it’s implemented that way.

DO: When disagreeing with feedback, explain the advantage of your approach.

In cases where you can’t reach consensus, bring the discussion on Slack with other peers from the team.


From an original source: https://testing.googleblog.com/2019/11/code-health-respectful-reviews-useful.html