- Arthur Coudouy
Do you think your reviewers leave your pull requests unnoticed on purpose? Is continuously asking for code reviews creating a small but persistent neurosis in your day-to-day?
Let's list why your team sucks at reviewing pull requests, and what you can do to improve it (before quitting your job).
Table of Contents
- I. Everyone is handling code reviews notifications differently
- II. Lack of a proper tool to help your team collaborate during code reviews
- III. Lack of dedicated time set aside for reviews
- IV. Not assigning specific reviewers for each pull request or assigning the wrong person
- V. Failing to maintain a culture of open communication and collaboration among team members.
I. Everyone is handling code reviews notifications differently
Not having the same notification system for code reviews is usually the #1 reason why your team sucks at reviewing pull requests.
Email notifications or GitHub/GitLab notifications are not adapted
Email notification, please stop
"Alex requested your review on her pull request." just hit my inbox. Only 48 unseen emails to read before I can start my day and review her PR. What a glorious day!
Email notifications might seem like a great idea at first, but before you know it, it turns into a chaotic mess. Sifting through them is like trying to find a needle in a haystack, and it's hard to keep track of what you've already looked at. Oh, and let's not forget about all those delightful emails from that recruiter you never contacted, and that JS newsletter you subscribed to years ago but never read. It's a wild ride, let me tell you!
GitHub/GitLab notifications are not adapted
I've been working as a developer for a few years now, and I've never seen a developer who felt like GitHub/GitLab notifications were adapted to their needs.
GitLab even called its notification system a "to-do list". Who needs another to-do list? I already have enough to-do lists, thank you!
Need to manually remind people in direct messages without context
Not knowing how your reviewers are notified about your pull requests often leads you to ... manually remind them in direct messages. All day. Everyday.
HEY CHARLIE, THIS IS THE THIRD TIME I'M REMINDING YOU TO REVIEW MY PR. I'M SURE YOU DIDN'T SEE MY LAST 2 REMINDERS.
Let's see why a dedicated tool will help you stay sane.
II. Lack of a proper tool to help your team collaborate during code reviews
Official GitHub & GitLab notification apps are outdated (too noisy) and hard to configure
Current GitHub & GitLab apps are outdated and hard to configure, they have major issues:
- They are too noisy,
- They are hard to configure.
Official apps are too noisy
Not everyone on your team needs to know about your new pull request. You don't want to spam them, and you don't want them to spam you.
PR notifications (especially reviews, CI/CD, and code comments) should only concern the PR author, assignees, and reviewers. Sending these notifications to a team channel is a bad idea. Another bad idea? Receiving notifications FOR YOUR OWN ACTIONS.
YES, I KNOW, THANK YOU GITHUB BOT THIS IS ME WHO OPENED THIS ISSUE.
Official apps are hard to configure when you start with them
When you start using GitHub or GitLab, you don't know what you need. You don't know what you want. You don't know what you don't know.
"I know that I know nothing" - some bearded wise Greek dude, probably.
These collaborative features should be easier to configure and start with an opinionated default configuration.
Implementing a custom solution is time-consuming and costly
A meme is worth a thousand words.
Implementing a custom solution is time-consuming and costly. You need to find a developer in your team that has time to do it, then you need to keep track of API updates, make sure your service stays online, and make sure it's secure.
Usually, you think that you have some special needs and requests, but trust me, even if each engineering team is unique, 99% of what you need can be generalized by a dedicated SaaS.
Using a dedicated tool is always a better option. And if your team is working on Slack, Axolo is the perfect tool for you.
Enable your team to mergepull requests faster with Axolo
III. Lack of dedicated time set aside for reviews
Not having dedicated time to review code, usually means that developers do it between two activities, they might rush it, or they might not do it at all. Reviewing code shouldn't be a burden or something we do as quickly as possible.
If you feel that your team is lacking behind code reviews, maybe implementing dedicated times to review pull requests is a good idea. You should ask developers in your team to dedicate at least 30 minutes a day to review pull requests.
If you'd like to know why reviewing daily is a good idea, check out this article.
IV. Not assigning specific reviewers for each pull request or assigning the wrong person
This creates bottlenecks and delays the review process
Most teams should have a process to assign specific reviewers for each pull request.
If you don't assign reviewers, who are in charge? Who's responsible?
I JUST FINISHED IMPLEMENTING THE 24 CHANGES YOU REQUESTED, AND NOW I SHOULD REVIEW YOUR PR VOLUNTARLY?
You should create a process
The code owner strategy to automatically request reviews
There are many ways to avoid confusion and confrontation while assigning reviewers.
The easiest way is to define code owners, they might be based on your team or people that already have an understanding of the code you're changing.
I think that it's important to have someone with experience looking at your code changes, but siloting the knowledge to a few people is not a good idea. What I advise is to implement two processes to assign reviewers for each PR:
- a code owner process dedicated to people with experience in this part of the code,
- a random process to assign another reviewer to each PR.
With these two reviews, you have the eyes of someone with experience looking at your code, and you help someone else better understand the company codebase.
Implementing reminders to wake your reviewers up
With a tool such as Axolo, you can implement daily reminders and let your code reviews continue on auto-pilot.
Reviewers will be alerted that some PR are waiting for their review, and they can review them whenever they have time.
No more stale PR, happy now.
Axolo is a Slack app to help techteams review pull request seamlessly
V. Failing to maintain a culture of open communication and collaboration among team members.
The last but probably the most important reason is failing to maintain a culture of open communication and collaboration among team members.
Code review is a great opportunity to learn from each other
Code review is a time to connect with your team, share knowledge, ask for help, improve yourself, and also help your teammates improve.
If you don't get this idea, you're missing the point of code reviews. Ask your team how they feel about code reviews, and see what you can improve. If you'd like a few ideas on how to ask your team for feedback, I've already worked on a developer experience survey template.
This can create animosity and a low willingness to review each other's code
If you don't have a positive experience while reviewing code, nothing else will help your team do it better.
A few points that your team should understand is that:
- Rules that are not written, do not exist (especially styling rules)
- Keep the team spirit and be kind
- Review daily and sessions should last less than one hour
- Understand what you're reviewing first
- Code review should be fast
If you want to learn more, I have detailed these points in a dedicated article: How to review code.
If you're struggling with code reviews, I hope that this article will help you improve your process. If you have any questions or any feedback, feel free to reach out to me on Twitter or LinkedIn, I'd like to keep improving this article.