Use Pull Request Templates to Improve Code Review Descriptions

Learn how to use a pull request template to ensure code authors provide meaningful code review descriptions. Pull request templates help populate your pull request (PR) with the correct information, so code authors remember what’s important to explain about their PR. A good code review description significantly reduces the review burden for the code reviewer, and is a code review best practice.

Reducing the reviewer burden

If you have ever done a workshop or coaching session with me, you will know my mantra of “reducing the reviewer’s burden.” This means it’s essential for a great code review experience to make code reviewing as easy as possible for the reviewer. Today, I’ll show you how you can use code review templates or pull request templates to help the code reviewer to understand the pull request. In addition, pull request templates are a memory aid for the code author.

You have probably seen it before: a pull request with several files changed and only the sparse PR title. Maybe the description consists of strangely worded commit messages, which will not help you understand what is going on in this pull request.

Why does this happen? Why didn’t the code author take the time to describe the change in more detail?

Code authors are the expert on the code change

The answer is that the code author is the expert on the code. They spent a lot of time deeply engaged with this code and the problem behind it.

Independent of whether they spend two hours, two days, or two weeks, they know much more about this piece of code than the code reviewer will most likely ever learn about it during code review.

Being an expert can be a disadvantage. This disadvantage is called the expert blind spot. The expert blind spot describes the phenomenon that an expert has difficulty assessing whether something is easy or hard.

Because of this, the code author will often assume that the review of their code is easy. Three files and 50 lines changed — that’s trivial to review in the mind of the code author. Therefore, code authors often do not write code review descriptions; and if they do, they only write extremely brief ones.

Are code review descriptions unnecessary?

In a study about code reviews I led at Microsoft, we asked code authors if they think sparse code review descriptions are sufficient to understand the code. The majority of the engineers said that, indeed, there is no need for a lengthy code review description. The few words or sentences are sufficient for the code reviewer to understand the change.

Yet, when we observed and interviewed code reviewers, we saw that this was not the case. Code reviewers struggled to understand the code, and were missing a lot of context that the code author could have easily provided.

We also saw that code reviewers that were given a good code review description which included the reasons why a change was needed, were more motivated and gave better feedback than code reviewers that lacked this information.

But is it enough to link to the issue?

When I ask developers to include better code review descriptions, many argue that they did link to the issue, and that this should really be enough information for the code author to understand this change.

While it is a good practice to link to the issue or ticket behind this change, it is not enough. Issues or tickets are made for the code author. They help track the status of the work. While they also often comprise a description of the problem, this description might be outdated. In addition, they lack several important pieces of information that a code reviewer needs to understand and assess the code change. For example, a ticket or issue seldomly or never describes which alternative solutions the author has tried before.

The code review description does not have and actually should not be a copy of the issue.

Instead it should briefly summarize information from the issue relevant to the code reviewer in the code review description. The majority of the code review description should contain information specifically created to aid the reviewer in understanding the change.

So, what is this exactly, you wonder?

What should a good code review description contain?

A good code review description comprises of all the information the code reviewer needs to understand the change better.

You can provide the reviewer with the following:

• Explanation of the change
  • the reason why this change is needed
  • why you have chosen this solution approach
  • which other solution approaches you considered and why you did not implement them
• Information on the quality of the change
  • are tests added (the answer should be yes)
  • do all tests pass (the answer should definitely be yes)
  • does the build break (again, no is not an option ;-)
  • are there linting or compile errors (no is what we want to hear)
• Guidance for the reviewer
  • what should the reviewers look at
  • where should they start the review
  • where is the main change/risk

In code review tools such as GitHub or GitLab, you can add a template that lets everyone know (code author and reviewer) what is expected from them. It’s also a great tool to make sure people remember what they should fill in and helps to overcome the expert blind spot.

Can you give me an example of a good pull request template?

Sure! For example, here is a screenshot of a minimalistic code review template from Spotify.

But you can of course include more helpful questions. I’ve created a GitHub template that comprises more template prompts, that you are free to use and tailor to your own needs.

“Pull request template”-Template ;-)

What does this PR do?

• What does this PR implement, and how?
• Why is this change needed?
• Which alternative solutions have you considered?
• What issues does this PR belong to?
• What type of change is this? (Feature/ Bugfix/ Refactoring/ Documentation)
• Screenshot/screencast of this PR (if appropriate)

How have you tested your change?

Please describe the tests you have performed to ensure the change is of high quality.

Code Author Checklist

• I kept my pull requests small so it can be reviewed easier
• I added automated tests that show my feature works or my fix is effective
• All new and existing tests passed
• Build and linting pass locally without warnings
• I updated the documentation and documented any public APIs

What should the reviewer focus on?

• Do you have specific questions/ areas for the reviewer?
• Where is the highest risk/ most complicated change that the reviewer should focus on?
• Is there a specific code review topic the reviewer should focus on (e.g., correct error handling, API usage)
• What is a good place to start the review (e.g., specific file/method?)