Code Review Tips for Authors and Reviewers

It’s well-known among software developers that the earlier they detect and fix an issue, the less time, effort, and money it will cost. Therefore, peer code review presents a golden opportunity for development teams to catch and mitigate potential issues before they have a negative impact.

Moreover, peer code review helps developers improve communication, share knowledge and expertise, and increase their sense of ownership, resulting in a superior overall product.

Over the past decade, I’ve worked with multiple companies of varying sizes and maturity levels, from being a one-man project to managing teams of more than 10 developers. Read on as I share some of the code review tricks for code authors and reviewers I’ve learned and benefitted from.

The author’s checklist

Review your code

This might sound basic to some and counterintuitive to others, but it works. While working on a feature, your perspective is confined to completing the task. After writing your code, try to take a break to clear your mind. Then, open your pull request and start reviewing your code. In most cases, you’ll be surprised by how many comments you can generate with fresh eyes.

A few years ago, I worked at a company where I was the only Android engineer. Technically, I didn’t need to create pull requests because I was the sole reviewer and approver. Yet I still created PRs throughout the day and returned to them first thing the next day with a clear head. And I would consistently find many issues and improvements that I overlooked while writing the code.

Narrow your scope

Large PRs require a lot of effort to understand and review; they’ll also generate plenty of comments. They’re harder for your team to review, take more time, and make it easy to miss issues in your code.

You should always break a large epic/story/task down into smaller sub-tasks, each with a narrow scope of change. Minimizing your code changes will keep your work organized and make your PRs simpler to review.

Document your changes

Code documentation is a huge asset for your team and your company because it helps you track product changes over time and serves as a great knowledge base for the whole team to learn from.

Detailing context not clearly visible through your code will make your documentation richer and more valuable. You should even include diagrams if they help explain your changes more clearly.

Listing all the modules, systems, and products your code will impact is another valuable addition you can make to your documentation. This approach will help your code reviewers and your QC/QA team when they test the feature.

Automate code styling

Automate code formatting, styling, and lining to save precious time while ensuring your code stands up to team conventions and is easy for reviewers to read.

The reviewer’s checklist

Understand the goal

Every PR either introduces something new or fixes something that was already there. Before going through the PR, take a minute to understand what it’s trying to achieve and how you would approach the goal if you were the author.

Compare solutions

Once you understand the goal and challenges, view the author’s proposed solution and compare it with the solution(s) you had in mind. Try to list the pros and cons of each solution and evaluate them against the following three factors:

• Time: Do we have enough time to plan and implement this change, or do we need to compromise? Remember, compromise doesn’t mean delivering something buggy or broken. It can be something like a solution that doesn’t scale well but gets the job done until you have the chance to refactor it.
• Complexity: Is the solution simple and to the point or overly complex? How does it compare with other available solutions?
• Performance: How does the solution perform in terms of memory, threading, storage, latency/speed, etc.?

Unit tests

Writing unit tests for your code is a best practice that helps software development teams improve test coverage, measure the health of a PR, and maintain code quality.

When reviewing a teammate’s code, always check the unit test he or she writes and make sure it covers all the scenarios you can think of.

Comment constructively

Always keep in mind that peer code review is not about evaluating your teammate’s programming skills. Avoid nitpicking, and try to provide constructive feedback that will genuinely help your teammate and improve their code.

To make your feedback more valuable and constructive:

• Phrase your comments as questions or requests rather than observations and commands.
• Don’t comment only on the negatives of the PR; leave positive comments about their code as well.
• Add code examples and other resources whenever possible to help explain your comments to the PR owner.

These code review tips have been a great help to me in improving my code and my team’s code. I recommend adding these code review checklists to your PR template to help your team write better code.