Code Review

How to write the perfect pull request

https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/

Approach to writing a Pull Request

• Include the purpose of this Pull Request

• Consider providing an overview of why the work is taking place (with any relevant links); don’t assume familiarity with the history.

• Remember that anyone in the company could be reading this Pull Request, so the content and tone may inform people other than those taking part, now or later.

• Be explicit about what feedback you want, if any: a quick pair of :eyes: on the code, discussion on the technical approach, critique on design, a review of copy.

• Be explicit about when you want feedback, if the Pull Request is work in progress, say so. A prefix of “[WIP]” in the title is a simple, common pattern to indicate that state.

• @mention individuals that you specifically want to involve in the discussion, and mention why. (“/cc @jesseplusplus for clarification on this logic”)

• @mention teams that you want to involve in the discussion, and mention why. (“/cc @github/security, any concerns with this approach?”)

Offering feedback

• Familiarize yourself with the context of the issue, and reasons why this Pull Request exists.

• If you disagree strongly, consider giving it a few minutes before responding; think before you react.

• Ask, don’t tell. (“What do you think about trying…?” rather than “Don’t do…”)

• Explain your reasons why code should be changed. (Not in line with the style guide? A personal preference?)

• Offer ways to simplify or improve code.

• Avoid using derogatory terms, like “stupid”, when referring to the work someone has produced.

• Be humble. (“I’m not sure, let’s try…”)

• Avoid hyperbole. (“NEVER do…”)

• Aim to develop professional skills, group knowledge and product quality, through group critique.

• Be aware of negative bias with online communication. (If content is neutral, we assume the tone is negative.) Can you use positive language as opposed to neutral?

• Use emoji to clarify tone. Compare “:sparkles: :sparkles: Looks good :+1: :sparkles: :sparkles:” to “Looks good.”

Responding to feedback

• Consider leading with an expression of appreciation, especially when feedback has been mixed.

• Ask for clarification. (“I don’t understand, can you clarify?”)

• Offer clarification, explain the decisions you made to reach a solution in question.

• Try to respond to every comment.

• Link to any follow up commits or Pull Requests. (“Good call! Done in 1682851”)

• If there is growing confusion or debate, ask yourself if the written word is still the best form of communication. Talk (virtually) face-to-face, then mutually consider posting a follow-up to summarize any offline discussion (useful for others who be following along, now or later).

bonus: https://github.com/thoughtbot/guides/tree/main/code-review

Code Review in Remote Teams

https://web.hypothes.is/blog/code-review-in-remote-teams/

Few don'ts mentioned on the article:

• Don’t just do the direct and minimal code review

• Don’t think that “criticize the code, not the coder” is enough

• Watch your tone

• Don’t be a back-seat coder

• Don’t break the rule of no surprises

• Don’t say things just to hear the sound of your own voice

• Don’t think that you have to find a problem in every code review

The articles also mentioned some do's. Please allocate some time to read the full articles for the full benefits.