CODE REVIEW EFFICIENCY

How to Write Better Pull Request Summaries

Code reviews are standard practice when working on web development projects for mid-market B2B manufacturers. 
Developers who review other people's code rely heavily on the pull request (PR) summary to complete these types of reviews. If the PR summary isn’t complete or vague, the reviewer must spend extra time reviewing the code and ensuring that all of the changes are covered. This slows down the review process and, ultimately, the entire project. 
Software developer Ben McLoughlin provides guidelines for a good pull request summary and a template that can speed up PR code reviews.

I’ve been asked to review the work of another developer on my team, and I’m feeling a bit angry, so I’m going to write an article instead! 

Below is a screenshot of a real pull request (PR) I’ve been asked to review. I’ve changed the name of the offender to protect his identity. The only line that matters is the one that’s highlighted; the rest is part of an overly verbose PR template that also makes me grumpy.

In this particular example, 12 files were changed, +508 lines were added, and -33 deletions were made. Yet, the summary is:

"Implement cart assessment service."

I admit that makes more sense to me than it would to another reviewer because I helped the developer come up with the name for the new feature, “Cart Assessment Service.” 

That's the point; I already know this. This summary tells me nothing about what I should be looking at, what has been changed, and how I need to test it. Now, I have to drop all my work and waste time trying to figure out how it works and whether I should approve it. The time he took to write the summary tells me his code can’t be trusted, so I definitely won’t approve it willy-nilly.

He thinks he saved time by not writing a summary, but the five minutes he saved would have saved me 20 minutes of frustration and wasted time.

What Makes a Good Pull Request Summary?

1. Start with Why

Begin by explaining the changes' purpose. It’s not enough to state the task or ticket number; give a brief reason for the change.

2. Link to Ticket

Including a direct link to the associated ticket or task in the description. The reviewer needs to compare your changes with the requirements and this makes their life a little easier. 

3. List Changes Made

Detail the specific changes you've made. This doesn't mean you need to describe every line of code, but outlining the key modifications will help the reviewer navigate your PR and understand what to focus on.

4. Provide Reasons

It’s common for reviewers to question why certain approaches were chosen. Explaining your decisions can preempt these questions.

5. Add Screenshots

Any visual you can provide helps add to the context of what the code is doing. Even if it's just a Postman Response with a new value.

6. Include Testing Instructions

Describe how the reviewer can test the changes effectively. Don’t assume they know what to do.

How to Write a Good Summary

1. Use a Template

To streamline the process, utilize a PR summary template. This helps maintain consistency and ensures all necessary information is included. Here’s an example of a template that balances thoroughness with brevity:

2. Review Your Code First

Before submitting your PR, review your own changes. This self-review not only helps catch mistakes but also aids in articulating what you’ve done when writing the summary.

3. Leverage Artificial Intelligence

Consider discussing your changes with an AI tool or chatbot. This can help you organize your thoughts and draft initial descriptions, which you can then refine to ensure clarity and conciseness.

Example of a Better Pull Request Summary

This is an example of a PR summary that I wrote before I knew I was planning to write this article. You might notice I forgot to add a link to the ticket. My changes were substantial, so I had to break them down into five primary sections.

Conclusion

Crafting effective PR summaries is a skill that benefits the entire team by reducing time spent on reviews and minimizing misunderstandings. While it might require a bit of extra effort, the payoff in terms of productivity and team harmony is well worth it. A well-written summary reflects your professionalism and respect for your team’s time and work.

Better code reviews mean better projects.

Want to know how Acro’s expertise can help your company reach its development goals?
Fill in the form below, and one of our subject matter experts will reach out.