pr checklist

This post contains checklists that intend to increase the value received from, and ease of, the code review process.

checklists reduce complexity

Checklists help to capture the information that we often forget. This post is aimed at software engineers who review code. This code review checklist covers the following areas:

1. Preparing for code review: preparations sets your reviewers up for success.
2. Performing a code review: think before you react, share your intentions and goals.
3. Responding to a code review: what to do when you’ve received the review.

You have a responsibility as the PR author and PR reviewer to make a code review function well. Code reviews are not just an input by the reviewer. There are things that the PR author can do to achieve the most value from a review.

how to read a checklist

You will see two different types of checklist; read-do, and do-confirm. The checklist types define the order in which you should read the checklist, and do the action.

Do-confirm checklists instruct you to complete the full the task, then check the checklist. Do-confirm checklists tend to be for simpler tasks. You should be able to remember most of the steps for this type of checklist. When you can remember most of the steps, the checklist operates as a safety net, to be read after. The checklist is to ensure you didn’t miss anything.

Read-do checklists instruct you to start by reading a single checklist item, then executing that specific checklist action. Once the step’s action is complete, you may move onto the next step. Read-do checklists are used for more complex tasks, where one of the following might be applicable:

• the order of the steps is important
• the steps are complex, and should be considered one at a time
• the outcome may be substantially different if a checklist step is missed

The following sections make use of the do-confirm and read-do checklist approaches.

checklists

preparing for a code review

[do-confirm]

Commit messages

• Set descriptive commit messages.
• Use imperative verbs; update, add, create.
• Use the active voice and not passive voice.

PR descriptions

• Include the purpose of the PR. This PR fixes handling of...
• Include an overview of the change, and why it’s happening.
• Describe the mental model of the code for the reviewer.
• Be explicit about the feedback you want. For example, one of the following (not exhaustive):
  • discussion on technical approach
  • critique on design
  • in-depth review of patterns and naming

Scope

• Identify scope creep, split the PR into multiple if necessary.
• Prefer fewer changes over more PRs.

performing a code review

[read-do]

Use the two-pass model

• Make two passes over the PR if it’s substantial:
  1. Understand the code change at a high level.
  2. Pay attention to the details, semantics, and style.

Written feedback

• Never use hyperbole (always, never, every).
• Differentiate a request and a demand.
• Use Nit: prefix to identify nit-picks.
• Share your intentions and goals.

Feature

• Ensure the change performs the intended function.
• Check the logic is correct.
• Check for reversible and irreversible changes.

Code style

• Code must be easy to read and understand.
• Explain your reasons for a requested change. Capture decisions in a style guide.
• Offer ways to simplify or improve the code, along with your requested change.

Code quality

• Expose the minimum interface. The larger the interface, the weaker the abstraction.
• No side effects.
• Use only one of “command” or “query” for methods.

Unhappy path and error handling

• Check defensively for error cases at the start of a function.
• Handle errors that are returned or thrown.

Tests

• The change should introduce zero known defects.
• Check for positive and negative test cases.
• Check of extreme and edge cases.

responding to a code review

Lead with empathy. Feedback is a gift. Reviewers are trying to help you.

[read-do]

Initial response

• Lead with an expression of appreciation, especially when feedback is mixed.

Ask for/give clarification

• Explain your intention behind design decisions.
• Ask for explanation on the comments that are not clear.

tips for reducing conflict in review

1. Consider, and truly believe that you could be wrong.
   • If you truly believe that you could be wrong, your code review comments will become exploratory and not accusatory. This reduces conflict.
2. Seek out what is true.
   • Seeking the truth will move your discussion from a subjective, opinion-based, discussion to an objective, data-focused, discussion. Seeking the truth also allows you space to be wrong.
3. Create a manual of style, or style guide to separate a discussion about this code from a discussion about how we do things.
   • Your disagreements become focused on the content of the style guide and not on the content of the PR. This allows code changes to progress while you decide how you want to structure and style your code. Once a decision is captured in the style guide, code changes must adhere to that decision. Until the decision is changed.