In best case scenarios, there’s a sense of excitement at the start of a project because it’s an opportunity to build something collaboratively with our partners. Passions are high and everyone knows the objectives.

The opposite can be true when projects begin with no context. For most organizations, the code review process can be challenging and tedious. That process can be even more difficult when developers receive a pull request without any background information. This can start the project off on the wrong foot and require more time for clarification.

Here are a few tips to improve the code review process so projects start strong and flow more efficiently throughout.

Pull Request Templates

We’ve recently started using pull request templates in one of our projects to provide the reviewer with some context of the work being done. This has significantly improved the process by reducing the amount of time the code remains under review and by eliminating the need for unnecessary back and forth between developers just to get up to speed.

Here’s an example of what to include in this template and what has proven to give the best results.

This template includes general components that should be considered when reviewing the code. However, because every company and every project is different, you may want to customize the template to better fit your needs. In addition to the pull request template, another practice that improves code review is a good git history, which leads me to my second tip.

Making a good commit message

Maintaining a good commit messages history provides you with useful information on what changes have been made and the reasons behind them. When I come across a commit message that says bug fix or add file, it doesn’t provide enough context. I know I’ll have to do additional legwork to navigate through the code so I can better understand what changes were made and how they affect the project as a whole. To eliminate this from happening, these are some guidelines I follow that can significantly improve your commit messages.

First, add a subject and a body to your commit message. The subject can be a single line that clearly sums up the changes and includes a reference to the issue being implemented. For example, if you’re adding a button to a form in the UI, a good subject line could be: Issue1234 – Add form submit button to main screen. Just that small amount of extra information can make a big difference and save time. Compare that to the message: add a new button.

In the body of the message, you should add bullet points that provide more details about the changes made to the commit. Using the earlier example, the graphic below shows a good commit message.

You can see how adding these simple descriptions gives the developer a clearer description of what was done, what parts of the code were changed and, lastly, what they should be expecting from this change. The subject and body are two components I use the most, but there are more tips you can apply to your commit. This is a great article by Jaiswal that provides more information on the subject.

Summary

Using a pull request template and adding a subject and a body to your commit message are two simple changes you can implement when reviewing and committing code. These have significantly improved our pull request review process and have allowed us to contextualize the request before getting into the code. Providing even a small amount of additional information on the front end can avoid countless problems related to bugs and failures in production environments down the road. We hope these tips save you some time and frustration. If you have any suggestions, we would love to hear about them and explore new ways to improve the process.

Give us your feedback! Connect with us now.