Code Reviews are Underrated
When I was an intern, I often wondered why code reviews took so long. As more of my pull requests (PRs) were reviewed and I started reviewing other people's code, I realized that code reviews are an important but underrated skill for any engineer.
The Value of Code Reviews
Engineers gain significant advantages from thorough code reviews:
Learning best practices of a language
Catching bugs early
Understanding tradeoffs among different solutions to the same problem
For example, I learned how to write effective RSpec tests and Ruby best practices after receiving suggestions on improving my code. I also started adding detailed descriptions to PRs when I saw how an old description in a PR helped me solve an issue.
In today's fast-changing world, where Large Language Models (LLMs) are used to generate code and tools like Copilot help us write boilerplate code, code reviews are even more important. While AI can be a powerful tool, it is not flawless. AI can sometimes hallucinate, producing code that appears to be correct but contains subtle or significant errors that do not fully meet all of the criteria for our use case. In such cases, it is especially important to review one's code.
Key Aspects of Effective Code Reviews
Understanding the Big Picture When reviewing code, our first instinct should not be to immediately suggest removing changes, but rather to ensure that we understand the context and purpose of the existing code. This principle, inspired by Chesterton's Fence, emphasizes the importance of understanding why a piece of code exists before changing or removing it. For example, in some cases, removing a piece of code after receiving review comments breaks the functionality. To avoid situations like this, one solution is to include comments or details about the unusual changes in the PR description.
Knowledge Sharing When we see multiple similar conversations/comments about coding style across different PRs, it indicates the need for proper linters and standardization. These linters and automated tools can handle a wide range of code quality issues, while human reviewers can provide insights into best practices, architectural decisions, and domain knowledge. This improves the learning experience and encourages a culture of continuous improvement.
Having a Review Buddy It's a good idea to have a review buddy with whom you can discuss design and architecture from the beginning of a code-related feature. This helps to avoid significant rewrites during the review stage and ensures that design and architectural considerations are aligned from the start. A review buddy can provide early feedback and suggestions, making the development process smoother and more efficient, which in turn speeds up the code review process.
Understand Testing & Deployment Plans As important as code reviews are for reviewing a piece of code, I believe it is also valuable to understand and review the feature's testing and deployment plans. One of the practices we've implemented in our team is to write a Minimal Effective Dose (MED) Testing Plan for each of our code changes, in which the code author mentions the critical pieces of the code that can be affected by the code change as well as test plans, which are then verified by the reviewer to make sure no edge cases were missed.
Suggest, Don’t Instruct Use a constructive and supportive tone when adding review comments as suggestions rather than instructions. Instead of instructing with phrases like "You should stop doing," use more collaborative language such as "I think it would be better to." Avoid using blameful or aggravating language.
Maintain a Priority List I usually keep a list of PRs and the expected date when the feature should go live. This allows me to organize the reviews by priority. Next, when reviewing the code, determine which parts are most critical and can cause production issues. Those hot paths should be reviewed first. This approach makes sure the most critical problems are addressed first.
Avoid Context Switch: Try to review code in a single sitting without unnecessary interruptions. Context switching can lead to oversight and reduce the quality of your review. Dedicate specific time slots for code reviews to maintain focus and provide thorough feedback.
Effective code reviews are a must for engineers. As technology advances with Copilot and LLMs, the engineer's role in ensuring the code is bug-free and meets standards through rigorous review practices becomes increasingly important.
Code reviews are more than just reviewing code; they also involve sharing knowledge, reviewing architecture design, and maintaining clear testing and deployment plans, all of which are beneficial to the development process.