Pull Request Best Practices in 2024

Let’s be real - pull request reviews are hard. Most times they’re painstakingly time-consuming. And more often than not seasoned team members have to step in and spend a lot of time assessing and providing feedback on new features or system updates. But, like it or not, they are an integral part of the software development process. That’s why engineering leaders need to make sure they have put the right code review processes in place.

In this guide, we'll dive deep into the technical aspects of pull requests and how they influence your team's productivity, code quality, and project outcomes. You'll learn some common pitfalls to avoid and leadership strategies to implement for pull request excellence. By the end, you'll have a holistic understanding of pull requests and how to leverage them as a key competitive advantage. So buckle up - it's time for a deep dive into the nuances of pull requests.

What is a Pull Request?

Picture this: A team of chefs is preparing a grand feast. Each chef is responsible for a specific dish, contributing to the overall menu. Think of a pull request like a chef presenting their dish for feedback. The head chef and others taste it, offering suggestions for improvement. This process ensures every dish is delicious and complements the entire meal. Similarly, in software development, pull requests are where code is reviewed and refined, making sure the final product is cohesive and top-notch.

Pull Request Best Practices for Developers:

Here are some general best practices pull request authors should implement:

Smaller Pull Requests

One of the best pull request practices is to keep them small and focused.
Developers can do this by keeping it somewhere between 200-400 lines of code by submitting:

• Functions
• Classes
• A small set of related changes

Following this best practice enables peers and senior developers to give their undivided attention to the code.

Having larger pull requests needs more time to review and offer feedback. That’s why, it’s always best to avoid them. Devs should aim to replace it with smaller pull requests for more efficient and effective code reviews.

In fact, software engineers at Redox conducted an experiment where they focused on creating very small pull requests (PRs) to understand their impact on development efficiency and satisfaction. Over six business days, they worked together on one service, resulting in 46 PRs merged/deployed to production, a consistent increase in the number of PRs created and merged per day, and a consistent reduction in the time any given PR was open.

This approach led to a significant increase in their velocity, beating the expected story point velocity by a factor of 1.5. They also experienced psychological benefits from the frequent reviews and improved communication about the code. The experiment highlighted that small PRs are not only more efficient but also more enjoyable for developers. This case study provides tangible evidence supporting the effectiveness of small pull requests in software development​

Write Contextual Title and Description

While committing changes to code, it's important to simplify and clarify the commit message for the reviewer.

You can do this by following the below pull request practices for writing commit messages:

• As a general rule, a commit message should have a maximum of 50 characters.
• Try to keep the description within 72 characters.
• Write sentences in imperative form, like "add button," rather than "adds button" or "added button." This avoids confusion for reviewers, allowing quicker code rollbacks if needed.
• Don't stress over complex grammar rules. Just avoid making declarative statements.

According to freeCodeCamp, here’s a perfect example of a concise yet informative commit message:

Avoiding Common Mistakes

Formatting

Messed code vs formatted code (Source: Medium)

Pay close attention to code formatting. A code that is consistent and readable ensures an improved review process. You should also try to use tools or plugins to automate formatting wherever possible.

Build and Test

Before submitting a pull request, ensure that changes do not break the build and pass all the tests successfully. You can catch these issues with the help of integration tools.

Code Dependencies

Verify that changes do not introduce conflicting dependencies or adversely affect other parts of the codebase. Isolation of changes helps prevent integration challenges.

Review Code Before Seeking Others' Input

Before asking for help from colleagues, reviewees should spend some time looking over their code. Hunt for possible mistakes, things that don't quite make sense, and spots where the code can be made even better. This step helps catch issues on your own and shows your teammates that you're committed to producing top-notch code.

Avoid Self-Approval

To ensure the objectivity and thorough evaluation of code changes, developers must avoid self-approvals. Many experienced developers are guilty of this, but it can lead to biases and other unnoticed issues.

Pull Request Best Practices for Reviewers

Time to switch the coin: let’s discover some recommended strategies reviewers should follow:

Never Skip the Timely Review

Code reviews are crucial for maintaining code quality and catching potential issues. The best practice here would be to conduct code reviews just after receiving a review request. Reviewing it in a couple of hours would be ideal.

Quick review and early feedback are helpful for developers since the context of the issue or feature is still fresh in their minds. This helps them to address the feedback promptly and effectively, keeping the development process moving smoothly.

According to Rewind, delayed reviews can lead to context switching for developers, which is time-consuming and can result in decreased focus and increased error likelihood. Prompt reviews prevent such inefficiencies and demonstrate respect for the efforts of peers​.

Avoid Unnecessary Discussions

Code change discussions are valuable, but It’s important to keep discussions focused and concise. Long and unnecessary discussions cause delays in the review process and also distract other team members

For complex and in-depth topics, you can encourage team members to have separate discussions.

For code comments, the focus must be primarily on the specific changes that are being reviewed. This helps in keeping clarity and cohesion during the review process.

Avoid Being the Judge and Jury

When reviewing code, it’s best to approach it with a collaborative mindset rather than a critical one. Of course, it’s your responsibility to ensure the accuracy of the codebase, but it’s ideal to do so in tandem with the pull request author.

If something in the code seems off, instead of jumping to conclusions, approach it with a spirit of constructive inquiry. This means avoiding a confrontational tone and seeking to understand the rationale behind the code changes. For example, saying “There’s an issue with this line” is far more constructive than saying “You messed up here”.

Wherever possible, reviewers should supplement feedback with helpful resources like relevant documentation or educational articles. This approach not only maintains a positive atmosphere but also fosters learning and growth.

Pull Request Best Practices for Managers

Here are some guidelines managers can use to foster a collaborative working environment and speed up code reviews:

• Clear Guidelines: Set clear coding, documentation, and testing rules for PRs.

• Early Collaboration: Foster pre-PR discussions to prevent conflicts.
• Constructive Feedback: Teach teams to offer solutions in reviews.
• Priority Reviews: Prioritize critical changes while balancing workload.
• Positive Recognition: Recognize outstanding PRs to boost motivation.

Miscellaneous Pull Request Best Practices

Apart from the pull request practices mentioned above, there are a few other best practices that you shouldn’t miss out on:

• GitHub suggests using informative and accurate labels according to type, stage, group, feature, department, etc.
• Use labels such as 'bug fix,' 'critical bug,' or 'button gradient features' to categorize pull requests
• Automate PR-related tasks
• While making a pull request, put the issue number in the title so everyone can easily see which task is being worked on and reviewed
• Offer visual aids, like  'before' and ‘after'  screenshots, while modifying existing features
• Make sure that pull requests include necessary unit tests for verification of the code’s functionality
• Use code quality tools to make sure that coding standards are followed

Leveraging Engineering Analytics Tools like DevDynamics

Engineering analytics tools like DevDynamics help engineering leaders track vital metrics such as:

• PR Size
• PRs merged without review,
• Time to Merge
• PR Cycle Time
• Code Churn Percentage
• PR Review Load

These metrics are crucial for understanding the effectiveness of your pull request processes. With DevDynamics, you can identify and resolve issues that could be slowing down your team, such as pull requests being merged without proper review, PRs lacking necessary testing, or lengthy reviewer response times.

DevDynamics provides comprehensive dashboards that offer clear insights into these metrics, allowing you to gauge your development team's performance throughout the software development lifecycle. This helps in making informed decisions to optimize your PR processes and overall developer productivity.