Pull Request Best Practices in 2023

Collaboration is the key to building exceptional products. And we step into 2023, mastering the art of pull request reviewing has become essential for developers and teams.

Employing these best practices can ensure smoother code reviews, faster feedback cycles, and improved code quality. In this blog, we'll explore the latest and most effective pull request practices for both code reviewer and reviewee.

But before that, let’s have a look at what exactly pull requests are.

What is Pull Request?

A pull request is like a message from one developer to the rest of the team, talking about the code they've changed. It's a way to talk openly and check over the changes together. If anyone on the team sees a problem with the changes, they can leave notes to talk about it.

Pull requests are important as they allow developers to propose and share their code changes with the team for review. This collaborative process helps identify and fix issues before merging the code into the main project. Pull requests also promote teamwork and learning from others, making code organization and version control easier. Overall, they play a vital role in delivering high-quality code to users.

Pull Request Best Practices for Developer:

Small Number of Lines of Code (LOC)

One of the best pull request practices is to keep them small and focused.

You can do this by keeping it somewhere between 200-400 lines of code by submitting:

• Functions
• Classes
• Small set of related changes

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

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

Simplify the Pull Request Title and Description for the Reviewer

While you commit your code changes, it's important to simplify the commit message for the reviewer.

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

• Keep the title of the message concise, like an email subject line, having a maximum of 50 characters.
• You can provide more details in the description, but try to keep it 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 and  you'll be fine.

Start Process Early With Draft Pull Requests

You can start the process early by seeking feedback as early as possible. It’s not necessary to wait until you're done with your changes to submit a pull request.

There are many platforms like GitHub, GitLab, and Azure DevOps that offer the option to create draft pull requests. These are also referred to as merge requests in GitLab, where you can gather feedback early on.

You can use draft pull requests to collect suggestions and input on your changes well before the actual merge takes place. This helps you to incorporate the feedback and enhance the quality of your changes. This practice significantly increases the chances of your pull request being accepted.

Comprehensive Testing Detail in Pull Request Description

Clear Context

Start the pull request description with a brief overview of the problem that you're going to address. You can also do the same for the feature you're implementing. This will help reviewers to understand the purpose of the changes.

Testing Strategy

Explain how you tested your changes. Share where in the code you looked, what type of testing you did (like checking individual parts or how they work together), and any specific examples of tests you ran.

Test Results

Provide the results of your tests that include both successful and unsuccessful results. This transparency will help reviewers to assess the impact of your changes on the codebase.

5. Avoiding Common Mistakes

Formatting

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 your 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 your changes do not introduce conflicting dependencies or adversely affect other parts of the codebase. Isolation of changes helps prevent integration challenges.

6. Review Your Own Code Before Seeking Others' Input

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

Pull Request Best Practices for Reviewer

1. 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 mind. This helps them to address the feedback promptly and effectively, keeping the development process moving smoothly.

2. 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.

3. 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 Managers

• 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.
• Tool-Driven Practices: Encourage usage of engineering analytics tools like DevDynamics for getting insights into the Pull Request lifecycle and understanding issues like large PR, idle PR etc.. Utilize DevDynamics working agreements to encourage adoption of best  practices such as no merging without review.

Miscellaneous Pull Request Best Practices

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

These pull request practices are:

• Utilize Informative Labels, Milestones, and Assignees.
• Use labels such as 'bug fix,' 'critical bug,' or 'button gradient features' to categorize pull requests
• Use tools like hub CLI to 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 code’s functionality
• Use code quality tools to make sure that coding standards are followed

Conclusion

When it comes to pull request best practices in 2023, working together and being efficient are key to successful software development. Using automation and having a culture of reviewing each other's code helps a lot. It's also important to use modern tools for better results. Remember to explain things clearly and give helpful feedback to each other. By keeping up with the latest trends and tools, developers can improve their pull request process, leading to better code, faster work, and a smoother development experience overall.

Want to understand how your team's doing with pull requests? DevDynamics can help you do that and more. Sign up for a free trial to unlock your team's potential.