Effective Code Reviews: Tips and Tidbits

Introduction

Recently I made the above post on X regarding how I think about code reviews. So a proper disclaimer that I have used AI to help reshape those points. You will also come across AI generated images which may or may not do justice to each point but that's an experiment!

That said, lets dive into each of them :-

The Challenge of Context Switching

Code reviews often require switching gears from your own work to examining someone else’s code. This context switch can be mentally taxing and disrupt the flow, especially when you're deep into building a feature or fixing a bug. However, sometimes this break can be beneficial, offering a fresh perspective on the task at hand. It's important to recognize when the context switch is helping and when it's best to delay a review until you're in the right mindset.

Provide Context in PRs

When I receive a pull request (PR) for review, I appreciate it when my teammates add comments or notes to guide me. These comments help set the context, explain the reasoning behind specific changes, and highlight any trade-offs made during the implementation. Providing this context speeds up the review process and ensures that the reviewer understands the motivation behind the code.

Trust Your Gut Feeling

Occasionally, while reviewing code, I get a gut feeling that something is off. The code might be getting overly complex, or a solution may feel too convoluted. While I might not always have the immediate answer, it’s important to communicate these concerns to the person submitting the PR. Complex code often leads to maintenance headaches down the road, so it’s always better to simplify where possible.

Ensuring Quality Before Shipping

Code reviews provide opportunity to improve code quality before it’s shipped. Once the code is deployed, it can take months before someone revisits it. Therefore, simplifying implementations, ensuring low coupling, and making code maintainable should always be top priorities during a review. This mindset helps prevent technical debt and improves the overall health of the codebase.

Urgent Changes: Clear Communication is Key

Sometimes, urgent changes need to be deployed, such as small edge cases that were missed or minor fixes. In these situations, it's crucial to communicate the urgency clearly to your teammates. Urgent changes should be concise and isolated to avoid introducing larger issues. Clear communication ensures that the priority of the change is understood, and the review process can be expedited.

Feature Flagging for Safety

There are times when a gut feeling suggests that a code change should be wrapped in a feature flag before being deployed to all users. If this wasn’t implemented initially, it’s worth suggesting it during the review. While this might add extra time to the release process, it provides a safety net and ensures quality.

Testing Code Locally

Running the code locally is often necessary to fully understand how it behaves from an end-user perspective. If the code doesn’t function smoothly or lacks polish, it’s important to address this before moving forward with the review. UX issues should be flagged early so that the code is in a reviewable state once it’s ready.

Addressing Changes in the Right Layer

Occasionally, during a review, you might notice that a change should have been made in a different part of the system. For example, security fixes are often best handled at the API layer, and certain UI-level calculations may belong elsewhere. Pointing this out helps ensure the change is implemented correctly and avoids unnecessary complexity.

Ask Questions and Identify Edge Cases

You won’t always understand all the code you read during a review. This is completely normal. Asking clarifying questions not only helps you understand the code better but also opens up discussions that may reveal edge cases or potential issues that the original developer hadn’t considered. These “what if” questions are crucial for identifying possible problems early.

Flexible Review Thresholds

After several rounds of reviews, the code may nearly meet your expectations. It’s important to maintain a level of flexibility, as the quality threshold can change depending on the complexity of the PR. The goal is to get the code shipped while maintaining a high standard of quality, so being flexible while keeping the bigger picture in mind can help move things forward.

Zoom Out and Think System-Wide

Code reviews shouldn’t just focus on the immediate code in front of you. It’s important to zoom out and consider how the change will impact the entire system. This requires a broader perspective, as one small change can ripple through other parts of the system. Sometimes, the problem may not even exist within your system but could be caused by third-party providers. Keeping this wider perspective ensures that the code fits into the larger architecture without causing unintended issues. I shared some real life experience on the zooming out bit here.

Keep Unrelated Changes Separate

Occasionally, you may come across PRs that include unrelated changes, maybe proposed by the founders/designers such as small bug fixes or quality-of-life improvements. These changes should be separated into different PRs for easier tracking and easier reversion if necessary.

Have Guidelines for PRs

It’s helpful to have a set of guidelines for raising PRs. At my workplace, we created guidelines for product engineering and added them to our PR templates. These templates act as a checklist, reminding the submitter to check for code quality, security, accessibility, and performance. Revisiting and updating these guidelines regularly ensures that they evolve alongside the team’s learnings and processes.

LLM-Generated Code: A New Layer of Review

In today’s world, many engineers are using large language models (LLMs) to generate code. While these tools can speed up development, they also introduce new challenges. As we rely more on LLMs, we become the default code reviewers for their output. It's important not to blindly pass LLM-generated code to teammates for review. Revisiting the code, analyzing its correctness, and ensuring it fits the project’s requirements are essential steps before sharing it with others.

Recognizing Your Limits

Lastly, it's important to recognize that you won’t catch everything in every code review. While the above stated points will help reducing the probability of unexpected issues, under tight deadlines or during times of high pressure, things will inevitably slip through. To minimize these oversights, avoid reviewing code when you're mentally exhausted or when you don’t have the capacity to provide valuable feedback.

Wrapping Up

Code reviews aren’t just about finding bugs—they're a chance to help make sure the code is clean, easy to maintain, and doesn’t introduce any unexpected issues. By taking the time to ask questions, provide thoughtful feedback, and stay flexible when necessary, you can make a big difference. And remember, code reviews are a team effort, so don’t hesitate to collaborate and learn from each other. It’s all about crafting better software together and making sure things run smoothly when they hit production.