Code reviews are one of the most important aspects of today’s software development workflow. They are a widely adopted approach because they help improve code quality, share knowledge across the team, distribute ownership, and standardize development practices. 

However, code reviews can also be stressful and time-consuming. One of the bottlenecks lies in Pull Requests, which can be one of the largest sources of frustration in the delivery process.

So how can you manage and improve your PR workflow to get your code to merge quickly? This article will give you 13 tips to make your team’s PR more effective. Let’s dive in!

#1 – Choose a branch naming strategy

The branch name is your first opportunity to give your task context. There are several strategies for branch naming, depending on how you manage work.

• If your task management tool gives your tasks a prefix, use it. For example, if the task name is XYZ-33: Implement login, a possible branch name would be XYZ-33_implement_login. A naming convention that includes a description will allow you to find the branch much faster.
• You can use the prefix approach, but prefix it with what it is: feature, bug_fix, refactor, among others — for example, feature_login.

You can follow any other branch naming strategy, as long as it is logical and consistent across your team. However, randomly naming branches can make navigating and maintaining branches harder.

#2 – Use the commit history in your favor

One code review approach you can use is per-commit review. Small and self-contained commits allow the reviewer to see exactly how you solved the problem. By reading the commit history of the PR, the reviewer can already understand what they’ll be reviewing, even before seeing a single line of code.

Here are some guidelines for good commits:

• Keep commit messages concise. GitHub wraps anything with more than 72 characters.
• Use self-contained commits with a single logical change in the code.
• For the commit name, follow the same approach you use in the branch naming strategy.
• Write the commit name before starting coding. It will help you stay focused on one task at a time and make your commits self-contained.
• On GitHub, you can use the Commits tab to review PRs with many small commits.

#3 – Review your PR and use static code analysis tools

Reviewing your code before opening a PR can help you find issues you may have previously overlooked. 

Static code analysis tools can help you prevent bugs and ensure that your code follows specific coding standards. You can set up your tool to run on every pull request and block merging if anything fails. You should then fix all the issues before opening the PR.

💡Codacy is the best-in-class solution for static code analysis. Integrating seamlessly into your workflows, Codacy helps engineering teams save time in code reviews and tackle technical debt.

#4 – Make your PRs small

Code review is not easy: you need to read code, understand what it’s doing and how it’s doing it, and look for potential problems. The more lines of code you need to check, the higher the chance you’ll overlook something. As such, it’s fair to say that the bigger the PR, the poorer the code review will be. 

There are several advantages of keeping your PRs small: 

• The review is quicker and more thorough;
• The PR is easier to merge (frequent merges lead to fewer conflicts);
• There is less wasted work if the reviewer rejects the PR.

#5 – Keep your PR clean

Making sure your PR is clean will help save time and keep the reviewer’s focus on the change at hand. Having a clean PR means, among others:

• Finding and removing all the debug logs and unused or commented-out code.
• Excluding code-generated files that don’t need to be reviewed.
• Dealing with the remaining TODO. You can either:
  • Implement them before opening the PR;
  • Create a new task or leave an estimation on when you’ll work on them;
  • Delete them if they are not relevant anymore.

#6 – Provide context with a good description

Remember that, unlike the reviewer, you’ve been working on the task. On the other hand, when the reviewer opens your PR, all they have is what you give them. So you’ll save everyone time by providing as much context as possible in a good PR description. When writing, try to answer the following questions:

• What task are you accomplishing with this pull request?
• How is it implemented (give an overview of your solution)?
• Why did you choose this approach (if several valid approaches exist)?

Besides answering these questions, your description should also include, if applicable:

• Link to the ticket in your task management tool;
• Links to related pull requests;
• Links to supporting pages that helped you reach your solution;
• Credit to co-workers that helped you in the process.

Finally, adding screenshots is always helpful if your task is related to UI changes. Plus, an animated gif showing the outcome of your PR gives reviewers a quick demonstration.

With this PR description, the reviewer will know what to look for and why you wrote the code the way you did. It will speed up the review, allow for better feedback, and lead to much quicker code merging.

#7 – Show your progress

In non-trivial pull requests, you don’t need to wait until you finish everything to open the PR. If you want an early review, but the code is not fully ready, you can mark the pull request as a draft on GitHub and put WIP (work in progress) in the title.

#8 – Share knowledge

PRs are not just about getting feedback from the reviewer; they’re also an excellent opportunity for the author to share their knowledge. For example, maybe you learned a new approach or a new feature of the programing language. Share this new information with your team.

#9 – Explain interesting lines of code

If your PR contains beyond trivial work, give reviewers additional information about why you wrote a particular line of code that way. Show your reviewers how you thought about the problem, and demonstrate the effects of the changes. The reviewers will know that your work was thorough.

#10 – Tell how to reproduce bugs

When fixing bugs, it’s helpful for the reviewer to know how to reproduce them so they can verify the fix. If the reproducing steps already exist in your issue tracking system, provide a link to the issue in the PR.  That way, the reviewer will know what the bug was, and it will be quicker to confirm it’s indeed fixed.

#11 – Demonstrate how to test your code

Tell the reviewer how to test your code. Providing a test environment and clear instructions on running the code and the tests will save the reviewer a lot of time and help them better understand your code.

#12 – Respond to comments

Once feedback starts appearing, be sure to respond to comments. By replying, you’re helping everyone keep track of the feedback that has been seen and considered. Of course, responding doesn’t mean you have to accept each piece of feedback, but it does acknowledge the reviewer’s time and effort in reviewing your work.

#13 – Thank reviewers for their suggestions

If you’ve reviewed code before, you know that deeply understanding someone else’s changes and giving valuable suggestions requires significant effort. So appreciate your reviewer’s efforts by thanking them. Plus, don’t assume you got everything right. Instead, be open to feedback, it will help you grow as a developer, and you’ll probably learn something new.

[Live Talk] Become a Code Review Master

Would you like to hear an expert dive deeper into code reviews? Join Codacy CEO Jaime Jorge in an exclusive talk with Curtis Einsmann, creator of the Master the Code Review course. Let’s have an open talk and share our questions.

Join us in our Talk Become a Code Review Master. See you there!

👉 When: September 20th, 2022, 4 pm UTC / 11 am CDT
👉 Where: online – registration needed