Effective Code Reviews
July 23, 2023
A well-conducted code review is an opportunity for both the author and the reviewer to learn, share knowledge, and contribute to the overall quality of the software. They are our shared journey towards excellence. The following guidelines may help both authors and reviewers carry out this task more efficiently and constructively.
As an Author, Value Your Reviewer's Time
One of the most critical aspects of an effective code review is respect for your reviewer's time. Here are some tips for authors:
Review Your Code Yourself First
Before submitting your code for review, go through it yourself. Look for typos, logical errors, and possible improvements. This preliminary review helps identify and correct minor issues before involving your reviewer.
Break up Large Changelists
It is easier and more efficient to review smaller, manageable chunks of code than large blocks. By breaking down your changes into smaller, logical units, you make the review process more effective and less overwhelming.
Automate the Easy Stuff
Automate tasks like linting and formatting using available tools. This way, you save your reviewer's time and ensure your code conforms to your team's standards without manual intervention. This is typically aligned on at the team or project level in advance.
Narrowly Scope Changes
Your code changes should be as specific and tightly scoped as possible. Including unrelated changes can confuse the reviewer and increase the chance of errors slipping through.
Respond Graciously to Critique
Accept constructive criticism positively and use it as a learning opportunity. Everyone makes mistakes, and a code review is a chance to learn from them.
Minimize Lag Between Rounds of Review
Prompt responses to review comments help keep the process moving and reduce the time spent on each review.
Artfully Solicit Missing Information
If you're unsure about something, ask for clarification. Constructive dialogue helps both the author and the reviewer learn.
Communicate Responses Explicitly
Always communicate your changes explicitly. Even if you've made changes as per the reviewer's suggestions, it's good to spell it out.
Don't Forget the Documentation
Good documentation is just as important as the code itself. It provides context and explains why and how the code works, thereby making it easier for others to understand your code. The same can be said of other project expectations such as tests.
As a Reviewer, Verify that Code is...
Required and Well-Designed
Check whether the code is necessary and fits well with the existing codebase. Each piece should interact with others harmoniously, contributing positively to the system's overall functionality.
Readable and Clear in Its Intention
The code should be easily understandable and its purpose explicit. This clarity is beneficial not only for end-users but also for future maintainers.
Commented with the "Why" vs "What"
Comments should explain why the code exists rather than what it's doing. This principle aids in understanding the rationale behind the code.
No More Complex Than Needed
Complex code is harder to maintain and more prone to bugs. The code should be as simple as possible without compromising its functionality.
Follows the Style Guide
The code should adhere to the team's style guide. Major style changes should be kept separate from the primary changelist.
Well-Tested and Documented
The code should come with appropriate tests and documentation. This practice helps maintain the code's integrity and allows others to understand it better.
Keep Code Reviews Constructive
Comments should be focused on the code, not the developer. Programming skill evaluations should not be part of code reviews. Avoid condescending or vague comments. Instead, be clear, specific, and include positive feedback where appropriate. Try to avoid being overly nitpicky; let automated style checks handle minor issues.
Lots of Good Criteria. Decide What Matters.
There are several criteria to consider during a code review. Does the code satisfy the requirements? Is it logically correct and secure? Is it performant, robust, and observable? Is there any unnecessary complexity? Are the API and internals cleanly split? Are there no breaking changes? All these are questions you should ask yourself when reviewing code.
In conclusion, code reviews should be respectful, constructive, and focused. Both the author and the reviewer play crucial roles in maintaining the code's quality and ensuring its long-term maintainability. Remember to keep an open mind, and always strive to improve. Happy reviewing!