Photo by Sebastian Herrmann on Unsplash
Code reviewing is an engineering practice used by many high performing teams. And even though this software practice has many advantages, teams doing code reviews also encounter quite a few code review pitfalls.
In this article, I explain the main code review pitfalls you should be aware of to ensure code reviewing does not slow your team down. Knowing which pitfalls and problems arise can help you to ensure a productive and effective code review experience. Those findings are based on a survey we conducted at Microsoft with over 900 participants.
A typical code review process
A typical tool-based code review process looks roughly like this: Once the developer has finished a piece of code, they prepare the code for being submitted for review. Then, they select reviewers who are notified about the review. The reviewers then review the code and give comments. The author of the code works on those comments and improves and changes the code accordingly. Once everybody is satisfied, or an agreement is reached, the code can be checked into the code base.
In another post, I described how a typical code review process looks like at Microsoft.
Code reviewing isn’t always a smooth process
These steps read like a smooth process. But, like everything, in practice, things tend to be more complicated than anticipated. During the code review process there a quite a few pitfalls that can reduce the positive experience with code reviews for the whole team. If not done correctly, code reviewing can also take its tolls on the whole team’s productivity. So, let’s have a look at the difficulties and pitfalls of code reviews.
The two main types of code review pitfalls are about the time spent on code reviews, and the value code reviews provide.
Be aware of code review pitfalls. Otherwise, code reviews can slow your team down. Click To Tweet
Waiting for code review feedback is a pain
One of the main pitfalls code authors face is to receive feedback in a timely manner. Waiting for the comments to come in and not being able to work on the code in the meanwhile can be a huge problem. Even though developers can pick up other tasks to work on, if the code review takes too long, it impacts the developer’s productivity and also the developer’s satisfaction.
But, why does the code review feedback take so long?
Developers have to juggle several responsibilities
Well, code reviewing is not the only task the code reviewer has to perform. On the contrary, code reviewing — even though it can take a significant amount of time of a developer’s day-to-day work — is only one part of the responsibilities and tasks of a developer. So, it is very likely that the code reviewer is engaged in other activities and has to stop or finish those first before looking at the code review.
If the timing is not ideal, and especially if the code reviewer hasn’t anticipated this change coming along, chances are, it takes a while before they look at the review. Remote teams also have to be aware of time differences. Otherwise, code reviews might even take longer.
Developers face problems if code reviews are not counted as actual work
Time constraints are real, and they affect both, the code reviewer and the author of the code. Doing a proper code review takes time. If teams want developers to do code reviews but do not value or count the time developers spend on code reviews, this becomes a real problem.
Not rewarding code reviewing efforts and performance
It does not help to claim to value code reviews if you do not reward the effort developers spend on this task. Many companies focus on rewarding developers for the amount of code they write or the features they develop. This decreases the motivation and the ability of developers to do a good job helping each other (which includes code reviewing). Code review effort and performance should be a cornerstone for performance evaluation or promotion decisions.
If you want your team to do code reviews well, reward them for their work. Click To Tweet
Social factors and team dynamics
But waiting on a code review had not always to do with the lack of time or missing reward system. Due to its social character, delayed reviews can be due to insecurities or team dynamics. Especially if the code review is overwhelming, or if the reviewer is new to the code, doing a code review can be overwhelming:
I’m expected to participate, but I’m not quite sure how. I’ll wait until someone else starts. — study participant
Large reviews are hard to review
Another significant code review pitfall is large reviews. Imagine you are the reviewer, and you just got this review. You think, well, I am quickly going to look at that, but once you open the review, you see this large code change. Several files have been changed, and all changes tangle throughout the code base. What’s your first reaction?
Probably: holy cow!
That’s right. That is exactly what we saw when analyzing thousands of code reviews. Not only does review time increase with the size of the code change, but also feedback quality decreases. Well, that’s probably understandable.
10 lines of code = 10 issues.
500 lines of code = “looks fine.”
Code reviews.
— I Am Devloper (@iamdevloper) November 5, 2013
Large code changes are just incredibly difficult to review. If, in addition, the code reviewer is not that familiar with the part of the code base the change took place in, reviewing can quickly become a nightmare.
Understanding code changes needs some guidance
Understanding code changes, and especially the motivation for a code change, is another code review pitfall many reviewers face. If there is no description explaining the purpose of the change, code reviewing becomes much harder. We saw in the study that if the code reviewer does not understand the code change, or if she is overwhelmed by the amount of change, she cannot give insightful feedback.
It’s just this big incomprehensible mess. Then you can’t add any value because they are just going to explain it to you and you’re going to parrot back what they say.
— interviewed developer13
Not getting valuable feedback decreases the developers’ benefit from and motivation for code reviews
Without a doubt, spending time on code reviews and not getting useful feedback back is a problem. Even though the team might still benefit from the knowledge transfer, the developer’s motivation to do code reviews and the benefits from code reviews decrease when they do not get valuable feedback.
There are several reasons why reviewers do not or can’t give insightful feedback. It can be that the code reviewer did not have the right expertise. Another common reason is that the reviewer did not have enough time to look thoroughly through the change.
Maybe the code reviewer does not understand the code. It can also be that the code reviewer does not know what issues to look for. Understanding what makes for valuable code review feedback and implementing best practices mitigates this pitfall.
Once the main discussion is about styling, you need to act
Another problem that can happen during a code review is called bikeshedding. Bikeshedding means that developers focus on smaller issues and start disputing minor issues and overlook the serious ones.
The reasons for that are manifold. Common behind the scenes challenges that lead to bikeshedding is that developers do not understand the code change or that they do not have enough time for the code reviews. Sometimes bikeshedding can be a sign that there are issues with the team dynamics.
Reaching consensus might need a face-to-face discussion
Sometimes it can happen that it is hard to reach a consensus. This can occur between code reviewer and code author, or also between several code reviewers directly. Such situations must be handled carefully as team dynamics are closely connected to these happenings. Communication via tools and in written form can aggravate this problem. If there seems to be any tension, or contentious issues to discuss, switching to face-to-face (either in person or via a video call) might be a good idea.
The benefits of code review outweigh the effort
I hope this list of code review pitfalls did not change your mind about code reviews. Because, the good news is that if you are aware of the code review pitfalls and counteract them, code reviews are a very beneficial engineering technique. And, there are even more proven ways to work effectively with code reviews.
Code review best practices
In the next blog post in this code review series, I show best practices to help to minimize the code review pitfalls and challenges and ensure your team gets the best out of the code review practice. So keep on reading. To be notified when I publish the next post, follow me on medium.
To never miss one of my posts, make sure you subscribe to my email list and secure yourself my VIP code review e-book, I exclusively prepared for my e-mail subscribers.
You can find me also on Twitter and I am more and more active on Hashnode! Love this community.
Originally published at michaelagreiler.com on April 6, 2019.