Reviewing Pull Requests



This is excerpted from a Datadog-internal post I wrote on code review best practices.
Profiling teams are splitting up OKRs into 2-3 person squads. This experiment is going quite well modulo some pain points around code reviews. As few squads have the luxury of more than one backend or frontend engineer, we need to get better at inter-squad reviews.

Also, we’re hiring.

Reviewing Pull Requests

Reviewers and authors experience an awkward power imbalance with the scales tipped to the reviewer. Even though the author has more time invested, they are dependent on the code reviewer’s oversight.

Here are some tips to make reviews more collaborative and higher quality.

Synchronous Reviews

Asynchronous Reviews

If the review can not be done synchronously, there are still things the reviewer can do to level up collaboration and reduce the power imbalance. All of these tips move the scale on time invested and power balance between author and reviewer.

Create a pull request against the pull

Rather than dictate suggestions as comments, try out the changes you want in another branch.

This demonstrates respect for the author’s time. If the review feedback is a good idea, it’s easy for the author to merge or cherry-pick the suggested changes. A low-effort review comment that forces the author to spend even more time can be demoralizing and should be avoided if possible.

Demonstrating the change rather than dictating is often net-time efficient and collaborative.

This technique is an effective shallow-feedback filter. Often in trying out a suggestion, the reviewer realizes a 5-second burst of insight during the review lacks context and is sub-optimal. Not adding that bit to the review is also a net-time improvement.

The author is (hopefully) receiving constructive feedback, but a reviewer can struggle to frame feedback as either a “nit” or go nuclear and block the review with “Request changes.” The above tips can help with the framing and make the experience better for both parties.

Review styles to avoid

Tooling tips

Github’s pull request UI is still :vomitemoji:.

IntelliJ IDEA has tooling for Github Pull Requests and reviews. Advantages include

More resources

Chelsea Troy wrote a series on pull requests.

Related tags:

site menu

Back to top