
Insight Blog:
Helping others review your code
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.
## Objective
A single line that describes the problem and what should be achieved in this pull request.
## Type
– [ ] Bug Fix
– [ ] New Feature
– [ ] Code Refactoring
– [ ] Documentation
– [ ] Tests
## Work Done
A technical description of the solution along with the changes made to the code base to achieve the main objective.
## Screenshots / Output
Add screenshots of the desired behavior or tell reviewers what they should expect from the changes stated above.
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.
Add:
+ New submit button to Contact form in the main screen.
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.