Many teams face challenges when conducting code reviews. In this article, we will look at the most common and problematic code review challenges and also outline how to overcome those.
Code review is an engineering practice used by many high-performing teams. And even though this software practice has many advantages, teams regularly face problems doing code reviews that slow down software development.
Knowing which problems arise during code review can help you to ensure a productive and effective code review experience. The code review challenges presented in this article are based on a survey we conducted at Microsoft with over 900 participants and on my years-long experience giving code review workshops.
A typical code review process
A typical tool-based code review process looks roughly like this:
Once a developer has finished a piece of code, she prepares the code for being submitted for review. Then, she selects reviewers who should review this code change. The reviewers then inspect the code and give feedback. The author of the code looks through the feedback and improves and changes the code if need be. Once everybody is satisfied, or an agreement is reached, the code can be checked into the common code base.
In another post, I described what a typical code review process looks like at Microsoft. And here, I describe how Google reviews code.
Code reviewing isn’t always a smooth process
These steps read like a smooth process. But, like everything, things are more complicated than expected. There are quite a few code review challenges that can reduce the positive experience with code reviews for the entire team and take a toll on the team’s productivity. So, let’s have a look at the difficulties and challenges of code reviews.
The biggest code review pitfalls are about the time spent on code reviews and the value code reviews provide.
Code reviews are only effective, valuable and fun, if you receive feedback in a timely manner. Click To Tweet
Waiting for code review feedback
One of the most frustrating problems during code reviews is waiting for code review feedback. Code reviews are only fun, effective, and valuable if you receive feedback in a timely manner. Waiting for the code review feedback to come in means that you are not able to work on the code in the meanwhile. So you either spend your time scrolling through Twitter, or you have to do a context switch and work on another task. Both 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?
Code reviews are a “necessary evil”
Code review is not the only task the developers have to perform. Even worse, in most companies and teams, developers’ main task is to write code, not to review code. This means that code review has a lower priority to developers than working on features. Depending on the incentives and how different tasks are valued in a team, code review might come even behind writing tests or attending meetings. In fact, at several companies, code reviews are seen as a “necessary evil”.
In addition, code review can take a significant amount of time in a developer’s day-to-day work. So, it is 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 expected this change to come along, chances are it will take a while before she looks at the review. Remote teams also have to be aware of time zone differences. Otherwise, code reviews might even take longer.
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.
You can’t expect quality code reviews if you don’t value the time a developer spends on them. Click To Tweet
Doing code reviews is not rewarded
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 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
Missing guidelines on code reviews
Another code review challenge is missing guidelines or training on how to do code reviews. If developers have no clear idea of what is expected from them during a code review, they also might procrastinate on doing code reviews. This increases the time spends waiting on review feedback. In addition, it reduces the value of the feedback because developers have no clear instructions on what to look for. Training on code reviews, which creates a shared understanding of the goals of code reviews, and how to do them, helps to overcome this challenge. In addition, teams can use code review checklists to guide developers through code reviews and make code review more systematic and effective.
I’m expected to participate, but I’m not quite sure how. I’ll wait until someone else starts.
Large reviews are hard to review
Large code changes, that span several files and consist of more than 400 lines of code create another significant code review challenge. Imagine you are the reviewer, and you just got a code review request. You think: “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!
10 lines of code = 10 issues.
500 lines of code = “looks fine.”
— I Am Devloper (@iamdevloper) November 5, 2013
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. Large code changes are incredibly difficult to review.
Large code reviews are hard to review. The quality of the review decreases with the size of the change, thus limiting the value teams get out of from code reviews. Click To Tweet
Reviewer is unfamiliar with codebase or technology
If, in addition, the code reviewers are not that familiar with the part of the code base the change took place in, reviewing can quickly become a nightmare. Similarly, if the reviewers are new to the technology or programming language, reviews are challenging for the reviewers. Do not expect developers that haven’t seen this piece of code before to make significant improvements.
No description of the code change is given
Understanding code changes, and especially the motivation for a code change is another code review challenge many reviewers
It’s just this big incomprehensible mess… then you can’t big,add any value because they are just going to explain it to you and you’re going to parrot back what they say.
Not getting valuable feedback
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 send their code for review decreases 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, using a code review checklist, and implementing code review best practices help to make sure the code author gets valuable feedback back.
Focusing on stylistic issues
Another problem that can happen during a code review is called bikeshedding. Bikeshedding means that developers focus on smaller issues and start disputing minor problems and overlook the serious ones. The reasons for that are manifold. Common behind-the-scenes challenges that lead to bikeshedding are 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.
If people dispute about minor issues during code reviews, take a look at the underlying issue. Time pressure, too large reviews, rivalry? Click To Tweet
Sometimes it is hard to reach a consensus. This can occur between code reviewers and the 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 challenges did not change your mind about code reviews. Because, the good news is that if you are aware of the problems during code review and take precautions, code reviews are a very beneficial engineering technique. And, there are even more proven ways to work effectively with code reviews.
So, keep reading more about code reviews, for example about code review best practices to overcome the code review challenges and ensure your team gets the best out of the code review practice.