Effective Code Reviews

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!

Read More