5 tips to boost the code review process
The code review process plays a key role in any software development company. Its main goal is to assure the quality of the software. It also has many other beneficial side effects:
- Learning — by seeing other peers code you improve your coding skills
- Knowledge Transfer — a good way to share new utilities, software architecture, and more.
- Finding better solutions — you can learn from other peers problem-solving skills
Despite all its benefits it tends to be quite frequently the bottleneck of the development. Why is it so? Quite frequently there is a big delay in code review quantity and quality. This can make the team frustrated and unproductive.
How can we unblock this? In this article, we look at some tips that will speed up this process. By following those, we will ensure to get more and faster code reviews. We will get and give more quality code reviews which boost any team’s productivity.
When creating a PR the developers tend to get a notification and an email. That normally should be enough for your PR to gain visibility. Unfortunately, sometimes it takes some bothering to get some eyes in front of your code.
Don’t be shy and remind people to review your code. They might have seen the PR notification but might have been dragged to another task. There are some vendors that let you re-trigger those notifications. That should be the first go-to approach.
If the re-trigger fails, you can use slack to request code reviews. You can choose the public channels first. You may add some context to make the task more appealing. If you keep on going unnoticed use direct messages. Those should be the last resource though.
There are some tools that can be used to further promote our PRs. By opting into those they will perform some automatic reminding. One awesome tool is
This slack bot will notify you from:
- Pending tasks to review
- Pending comments
- Mentions in GitHub
It will target developers with friendly reminders.
Promoting is always a wise choice. However, before airing out our PR we should make sure it is in good shape. How would we know that? By following the below tips.
It is quite common to start a task and to identify some potential risks and problems. Sometimes we might encounter some legacy code that could use a good refactor. Other times the task might become too big. That is why it is important to plan ahead instead of diving straight into coding.
What we must do is identify all the potential issues and divide them into subproblems. We can create a subtask for each of those subproblems. That would help keep our PR short and contrived.
Our PRs should remain short and well-scoped. Nobody wants to review long PRs. There are just too hard and tedious to reason about. Some unexpected errors might be buried in the long list of changes.
By shipping only the bare minimum of code it would be much easier to review. That means more and faster reviews. Less code tends to mean fewer bugs and therefore fewer back and forths. Those are likely to lead to an unproductive and unpleasant experience.
Maintaining good PR etiquette is also crucial to getting faster reviews. The description field is not a section to be ignored in your PR.
Provide a summary explanation of the purpose of the PR. Your fellow peers have to be able to tell at a glance if it’s a bug, feature, integration tests, etc.
- If it’s a bug, explain your findings and a brief summary of how you fixed it.
- Include any visual information that will help others understand better what this task is about. Screenshots are always welcome, especially on new features. They help others picture what’s been built. Non-technical people appreciate those.
- Include some tasting notes to help QA test better your changes.
Most git providers have the PR template feature. By making every developer fill a template those will become more consistent.
Providing consistent commits will give more context. There are some guidelines that we can follow. I like to use this emoji guideline here.
Let’s look at an example:
git commit -m "JGM-3 ✨ adding social sign on"
In the above commit we can see:
- ✨ — this emoji states that the above is a new feature
adding social sign on— a clear message of the added feature
The code review process is a shared responsibility. It is a two-way street. We can’t possibly expect anybody to review our code if we don’t review theirs. The more we review, the more visible we become.
We all know that code review is a daily responsibility. Why not allocate some time for it then? We can block a recurrent time event in our calendar. This will create a daily review habit.
Another critical aspect is how we give feedback. We must give friendly and professional advice. It is a good idea to establish or pick up some comment guidelines.
My preferred one can be found here. It consists of prepending an emoji at the start of each comment.
That emoji will help contextualize our comments. It is not the same trying to discuss further ideas, nitpicks, or things needing to fix. I find emojis to add a friendlier tone to the message also.
The importance of testing can never be overstated enough. It helps us identify defects, reduce flaws and increase the overall robustness of our code. We can understand how our code deals with corner case scenarios. We can divide tests into three categories:
- Unit tests
- Integration tests
- End-to-end tests
Those together form the Testing Pyramid. It is a framework that helps both developers and QAs to ensure that high-quality software is produced.
Adding tests doesn’t just increase the quality of our code. They also serve to self-document your code. This will reduce the time it takes for anybody to understand any business logic or corner case scenario.
Without tests, there is no good way to assert that the expected result is delivered. Nobody wants to approve a PR that adds any risk to the product.
That is it. Our motto has to be: keep it simple and transparent. The easier we make it for our peers to review our code the more happily they will review it.
Ideally, we will be producing pull requests in the same shape we would like to review them.
Mastering the code review process is a must-have skill for any software engineer. We are likely to spend some meaningful time daily in that process.