Challenges and solutions in code reviews

Greg Foster
Greg Foster
Graphite software engineer

Code reviews are essential for maintaining high-quality code, but they can also present significant challenges. By understanding common issues and implementing effective strategies, teams can overcome these hurdles and streamline the review process.

Imagine a developer named Alex who has just completed a major feature implementation. The pull request submitted spans across 1,000 lines of code and touches various components of the system. The reviewer, Jordan, is overwhelmed by the sheer volume of changes and concerned about the effectiveness of the review. Jordan requests that Alex divide the pull request into smaller, more focused segments that can be reviewed more efficiently. Alex complies by creating separate pull requests for the database schema updates, the new business logic, and the user interface changes. This segmentation makes it easier for Jordan to review each part in detail without missing critical issues due to cognitive overload.

Challenge: Large code reviews can be daunting and are less effective since reviewers' ability to identify defects diminishes as the size of the review increases.

Solution: Encourage developers to submit smaller, incremental changes. If a large review is unavoidable, have the developer provide a clear outline of the review structure and consider splitting the review into manageable parts. If the code review is too large to handle at once, ask the developer to break it down into smaller, more digestible chunks, or at the very least, provide comments on the overall design for initial improvements​​.

In another scenario, Sam, a seasoned developer, proposes a significant redesign of a feature during a review, but the original author, Riley, is resistant. Riley feels personally attached to the design and is confident in its merits. To resolve this, Sam and Riley decide to sit down and discuss their viewpoints. During their conversation, they explore the benefits and drawbacks of each approach. A third developer, Taylor, who has experience in both areas, is called in to provide an unbiased perspective. Together, they agree on a hybrid solution that incorporates the best aspects of both designs, satisfying both parties and improving the feature’s quality.

Challenge: Disagreements can arise during reviews, and developers may push back against suggestions, sometimes due to ego or a sense of ownership over the code.

Solution: Foster an environment where all feedback is seen as constructive. When disagreements occur, take a step back and evaluate the developer's perspective; they might have insights that the reviewer hasn’t considered. If the reviewer’s suggestions are indeed beneficial, they should persist politely, reinforcing the aim to improve code health. It's important to remain courteous and respectful throughout the process, ensuring the focus is always on code improvement rather than personal criticism​​.

Lastly, consider Casey, who is in the middle of writing a critical piece of code when a notification for a code review pops up. Knowing that a prompt review is beneficial for the team's velocity, Casey is torn between continuing the immersive task and responding to the review request. To balance personal productivity with team needs, Casey decides to finish the current coding task before taking a break. During the break, Casey reviews the submitted code, providing timely and valuable feedback without interrupting the flow of development work. By managing their time efficiently, Casey contributes to the team's progress while also maintaining personal productivity.

Challenge: Slow review processes can decrease the entire team's velocity, delay new features and bug fixes, and lead to frustration among developers.

Solution: Respond to code reviews promptly, ideally within one business day, to maintain the momentum of the development process. Utilize tools and practices that allow for quick, iterative feedback without compromising the quality of the review. For instance, giving a conditional LGTM (Looks Good To Me) can be used to keep the process moving while minor issues are addressed. Always strive to unblock the developer as quickly as possible without sacrificing the health of the codebase​​.


Implementing these solutions can help overcome common challenges in code reviews, ensuring that the process remains a productive and positive experience for all involved. It’s essential to balance the need for thorough, quality reviews with the practicalities of working within a dynamic team environment.

Git gud
"It's the first Git workflow I've used that actually feels good."
–@robboclancy
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2