15 Best Practices for a Successful Code Review

After spending your morning documenting feedback for your newest colleague, you shoot off the code review.

Rubbing your eyes after looking at the screen for too long, you glance at the clock.

Lunch time!

Coming back with a renewed focus (and a stomach that’s no longer grumbling), you’re ready to dive into your own project. You have just enough time to finish this code change by the end of day.

But as soon as you open your computer, you glance at Slack and see your colleague sent back his initial response while you were at lunch.

He has several questions and sounds a bit annoyed about one the changes you recommended.

You start typing your response, knowing this is going to take a while…

Code reviews are crucial for shipping code that’s not riddled with bugs or technical debt. They’re also often frustrating.

In this article, Rob Liebowitz, Senior Software Engineer at global data intelligence startup Morning Consult, shares some best practices for code reviews.

If you’re still reeling from the headache of your last review or simply want to improve your process, then these tips are for you.

 

 

Kicking off the Code Review? How to Dive In.

Knowing where to begin with a code review can ensure you make the most of your time.

When starting a code review, Rob recommends following these steps:

• Pass over the whole change set. Before looking at the code itself, look at the title and description of the change and make sure you know what to expect from a functionality perspective.
• Quickly scan and look for the big pieces of functionality that are being changed. Consider: Are there any changes to the public interface, the APIs, or the documentation that direct why this code is changing and the main drivers of the change?
• Do a deep dive. Once you’ve made your way down and gained a better understanding of the high-level pieces, it’s time to dive in fully. Ask questions such as: Does the structure of this make sense? Are there any errors in here? Do the abstractions and mental model line up the way I expect them to?

Rob summarizes, “In the end, it boils down to this question: Is there anything that the author did that I would have done differently? If the answer is yes, it doesn’t mean that either person was wrong; it means there’s a learning opportunity. Both the reviewee and reviewer gain exposure to the fact that there are multiple ways to write the code.”

 

Unfamiliar with the Code Base? How to Provide Valuable Feedback.

There may be times when you have to review code that you’re not a subject matter expert on. Don’t sweat it. You can still offer value.

Rob explains that this is very common among engineering teams and that bringing fresh eyes to a technology or programming language can enable you to provide a new perspective.

When you’re reviewing code on a product or technology that is unfamiliar to you, these tips can help you still conduct an effective and helpful review:

• Remember that asking questions is helpful for everyone involved. It encourages the author to explain themselves. Why did they write the code that particular way? Was that the cleanest way to write it? When the reviewer has a lot of questions on a change set, it may be a signal that something isn’t as clear as it should be.
• Focus on improving areas that transcend the specific technology. You might not be as experienced with a particular technology, but you can keep an eye out for clear documentation, function length, the complexity of the code (i.e. does it look manageable), and whether there are test cases for all the business scenarios.
• Loop in others into the review process. Just because you’re the person tagged on a code change doesn’t mean you have to be the only person looking at it. When you’re writing your review, tag other people for a specific question. For example, you could write a note saying, “This change looks good to me, but I know Alex over on the DevOps team has a better understanding of what that process looks like. If we can get their review as well, I’d be a lot more comfortable merging this change in.”

 

Reviewing Someone Else’s Code? How to Critique (without stepping on toes!)

There’s a lot to take into account when you’re communicating with another developer during a code review. After all, to some degree, it’s a vulnerable place for the person whose code is being reviewed.

Rob shares his go-to reminders when giving feedback:

• Take extra care to focus on the code and not the person who wrote the code. For example, you could rephrase comments like, “You need to change this,” to, “The code might be better optimized if we rewrote it as…” When you focus on the code, that naturally lends to coming across as helpful rather than combative. The person receiving your feedback will likely be receptive if you come across as being on their side.
• Make suggestions clear and actionable. Avoid negative or vague comments: “This doesn’t make any sense” or “I’m not sure what’s going on here.” Instead, do your part to understand the code, so you can provide constructive feedback: “The name of this function doesn’t seem to match what the function is doing. I’m not sure which of those two things is supposed to be correct here.” Or “You’re using a map here, which is being accessed by multiple threads. Maybe we need to protect it with a Mutex.”

 

Getting Code Reviewed? How to Set Your Reviewer Up for Success.

One step that makes a code review successful is the preparation beforehand. Rob recommends the following steps to make sure you’re passing off the best code possible (and thus, making the best use of everyone’s time).

• Manage the size of the change set. The more code that ends up in a code review, the worse the review is going to be. If you write a single line of code and submit it for review, people can work through it quickly and give a detailed response. But if you submit a thousand lines of code all at once, people will likely say, “Yep, looks good to me.”
• Follow your team’s code review checklist. A lot of teams have “definitions of done” or checklists of things they need to do before a merge request or a pull request is ready for review. For example, your team might require tests to be part of every change. If so, be sure to write your test before passing it off for review!
• Consider getting feedback before the formal code review. It’s totally fine to go to another team member and say, “Hey, this is a draft. Can you help make sure I’m heading in the right direction?” That will ensure the final change set is of much higher quality before it hits the review stage.
• Keep an open mind. Remember: the goal of the person reviewing is to improve the code base and ensure the changes make sense. Feedback for improvement is not a slight against you or the way you’ve done things. You don’t have to agree with everything they say but keep an open mind to receive their feedback and look for areas where you might grow.

 

Running Short on Time? How to Speed Up Your Code Review.

We’re all pressed for time, especially when trying to push out a code change to meet a client deliverable. Liebowitz shared the following tips to streamline the process.

When Writing Code:

• Automate your process. Automation tools (Think: Static analysis or linting) can help save a lot of time because you’ll get feedback inside your editor as you’re writing code as opposed to pushing code off and waiting for another person to get back to you.
• Use style guides. Work with your team to come up with those guides so that you’re all on the same page and know the requirements. If you can end a discussion before it happens, that’s a huge time saver!

When Reviewing Code:

• Give yourself a time limit. If your reviews are taking more than an hour then it may be something you need to address by breaking it up into small, more manageable pieces.

Note: The other benefit of smaller change sets is that they’re easier to manage from a Git history perspective (it’ll be easier to revert things or understand why a change was made).

• Cut down the back and forth. A lot of time can be wasted when the author and reviewer keep sending messages to each other. If you start reviewing a code change riddled with problems, it may be worthwhile to schedule a meeting to walk through it together instead of leaving asynchronous comments back and forth.

 

Is Your Team Growing? How to Scale Your Code Review Process.

If you’re part of a small team that’s growing, this will certainly impact your code review process.

The team members who are very good at code reviews typically step into new roles, preventing them from spending as much time on the actual code base.

Liebowitz recommends these tips for engineering teams that are scaling:

• Increase the number of developers who conduct reviews. You have more work being produced, so you need to increase the number of team members who are equipped to review it. This will help you distribute work and avoid bottlenecks that come from only one person being able to review all the changes.
• Conduct knowledge shares. Have your engineers teach one another about the projects and technology they’re working on. Make sure multiple people understand every change that goes into the code base. That way you don’t end up with a scenario where one person writes something solo and it’s not seen until after they leave the company when somebody else picks up their work.

Conclusion.

Now it’s time to take these tips into your workday! Pick one or two of the tips that stood out the most and incorporate them into your next review.

Ready to get your whole team on board? Take a moment to share this article with your co-workers. Then reach out to them to bounce ideas around which tips should be implemented in your team’s code review process.

Happy reviewing!