Most teams experience the frustration of dealing with broken code. Good teams take the time to consider how to reduce the chance of producing code that does not work. And great teams take the time to ensure they're producing the best code possible. Code reviews are the single best way to achieve those goals!

A solid code review process provides a structured way for team members to review and discuss each other’s code. They take time, but that extra time is worth its weight in gold when you consider the benefits. Combined with other forms of testing, code reviews can help reduce the total time spent on quality assurance.

Code reviews have a higher rate of bug discovery than traditional testing. They also provide mentoring opportunities and cross-module knowledge sharing for your entire team. In other words, code reviews are the single most cost-effective way to find bugs in your software.

Higher quality code. Increased educational opportunities. A more knowledgeable and flexible team. The power of a consistent code review process is extensive. Let’s explore these reasons in a little more depth.

This guide will help you integrate code reviews into your existing development workflow with no effort. The workflow was built around Beanstalk’s Code Review tools that make it super easy to conduct code reviews and ship better quality projects to your users. Now let’s jump right in!

Why code reviews?

The single most important goal of code reviews is to discover more bugs. At this, it excels. Inspecting code uncovers issues that are difficult or impossible to find using other methods. Code inspection is better at exposing subtle logic problems that are less obvious during manual testing. Also, if the bug is due to a misunderstanding by the original developer, the broken logic can extend to the automated tests. If the logic and test contain the same bug, code reviews are your last chance to catch it before manual testing. Once manual testing begins, the overhead of finding and fixing the bug increases significantly.

Code reviews mean more eyes on the code and an increased likelihood of exposing mistakes. They also include team members with more experience adding their input and insight.

If the primary goal is uncovering bugs, the secondary goal of code reviews is to keep the quality high. This is more subjective, but it’s one benefit that no other form of quality assurance can provide. And it can be just as important to the long-term stability of your codebase.

Even if code is bug-free, there may still be opportunities to improve it by refactoring. Catching these opportunities earlier when the code is still fresh on a developer’s saves time and makes the code easier to refactor. Better code also decreases the likelihood of introducing new bugs in the future. And, as developers learn to expect scrutiny, they’ll become more proactive about writing better code to begin with.

Code reviews find more bugs and increase the quality of your code base. Those two reasons alone make a strong case for code reviews, but code reviews also offer the benefit of education. First, junior members of your team learn techniques from your more experienced team members. Second, everyone on the team becomes more familiar with others’ areas of the codebase. This is mentorship at its best.

As a sort of an extension of education, another subtle but key benefit is that of shared ownership. The team will collectively feel greater involvement towards the application as a whole. This creates a better understanding of relationships between modules and decreased feelings of territory. That way, when a team member wins the lottery and quits, the rest of the stands ready to jump in and fill their shoes.

This all means that code reviews can save time and money in the long-run. Since you’ll uncover issues earlier in the process when they're fresh on developers' minds, you save time fixing them. You'll also avoid the communication overhead between testers and developers during manual testing. Your codebase will become more maintainable, saving time and money during future changes. Fewer total bugs means fewer support requests and lower support costs. Your customers love the increased reliability, and everybody wins.

Hopefully, at this point, the only question you’re asking is “How do I get started?” Fortunately, that’s next.

How can we do this?

Many teams view code reviews as a hassle with extensive scheduling and meetings. Fortunately, it doesn't have to be that way. Unfortunately, creating a culture of reviewing code takes time and effort. With a few tips, you can improve the chances that your team will embrace code reviews.

Review your own code first

If each team member reviews their own code beforehand, they'll catch some obvious mistakes. That will save time during the code review when so others won’t have to spend time on simple issues like typos.

Don't skip code reviews

Code reviews need to be an unquestioned step of your process, and team members need to hold each other accountable. It will be tempting at some point to skip a code review in favor of expediency, but that is a slippery slope. No code is too short or simple for a code review. If it's short and simple, the review will go quickly. Once your team gets the process, they won't be able to imagine doing it any other way. For example, your policy could be “Nothing ships without a code review by at least one other team member.”

Use automated tools for the nit-picky stuff

Automation is your friend, and tools like Code Climate and Hound make this easy. Peer code reviews need to focus on logic, structure, and organization. Not indentation, non-standard variable naming conventions, and other bad practices. Let static analysis tools and linters do the legwork on the tedious bits. This way, your team members can focus on the high-value aspects of your code reviews. This also brings the added benefit of team members not missing the forest through the trees. Too many minor issues can often make it more difficult to see and address the larger issues.

Use a checklist to guide focus

While reading over code will find issues, it’s often easy to forget and overlook some of the most common types of more subtle mistakes. Also, while it’s easy to see mistakes that are in the code, it’s not as easy to recognize code that's missing. Depending on your technology stack, domain, and other factors, it’s often handy to make a checklist of common types of mistakes to watch for. This helps ensure that reviewers are looking not only for mistakes to fix, but also opportunities to improve the code.

Common Mistakes

Here are some common examples of items that are often overlooked when focusing only on looking for mistakes…

• Is it well commented?
• Is the relevant documentation updated?
• Is there adequate test coverage?
• Are there any exceptions to expect and handle?
• Is there adequate and thorough logging for the new code?
• Are the labels and names logical and easy to follow?

That covers the high level tips, but there’s still quite a few soft topics that are worth addressing. It’s human nature to struggle with some of these challenges, so a few tips and guidelines can go a long way.

Tips & guidelines for team members

We all struggle with collaboration from time-to-time regardless of context. Establishing guidelines with the team can help everyone stay on the same page with healthy collaboration. So we've pulled some basic guidelines together to help you jumpstart the process.

• No personal attacks. Remember that everyone’s on the same team and working towards the same goals. Also, remember not to take any feedback personally.
• Keep it constructive. When you find a mistake, don't stop at pointing it out. Make sure to take the opportunity to suggest a solution and turn it into a teachable moment.
• Subjective suggestions are just as important. Code doesn’t have to be objectively bad. If code is difficult to understand, it’s reasonable to share subjective ideas. Just remember to avoid debating the philosophy and instead focus on the relative merits and tradeoffs of the individual ideas.
• Questions are great. The best feedback and learning opportunities come out of asking questions. If you don’t understand a section of code, mention it. Either you'll learn something new, or your confusion will help the author see that maybe the code isn't clear enough. Then they can step back with fresh eyes and tidy it up a bit.
• Always involve at least one other person who didn’t write the code. At the same time try to keep the total reviewers to a manageble number. It helps to have more eyes on the code, but too many eyes can be counter-productive. Usually, the best approach is to select one to three people who would be best suited to give feedback for a given module.
• Remember that it’s better to have small lightweight reviews than nothing at all. If your team can’t initially commit to doing in-depth code reviews, start small. Let the benefits speak for themselves and increase your commitment to code reviews over time.
• Remember that it’s ok to not find any problems. If you’re reviewing 100 lines of simple code, it’s entirely possible that it won't need changes. Don’t look for problems just for the sake of finding problems.
• Ask or teach without giving orders. There’s a big difference between saying “Change this to something more readable.” and “I’m having a hard time following this code because this part seemed ambiguous.” Or even “This is confusing. Is there a way you could tweak it so that it’s more obvious what’s going on?”
• Remember to think big picture. Micro-level suggestions are good, but it’s also important to consider how code fits in and interacts with other modules. Is this the best place for this code to live? Does the naming and organization follow team standards? Always remember to think about both macro and micro.
• Remember to be positive and point out good things as well. This seemingly minor tip can work wonders. When people only hear negative feedback, it can be overwhelming. A few kind words and acknowledgements can help reverse the tide. This can also help reinforce good habits that other reviewers might not have known about and can adopt for their own code.

These guidelines are a good start, but thoughtbot has also put together a great set of more specific guidelines for code reviews.

Like any change in process, this will take time, but once you’ve gotten rolling with it, you won’t want to go back. Phase it in over time, and remember that code reviews aren't adding extra friction. They're shifting some friction earlier in the process to save more friction down the road. That is, you're encountering the friction before releasing the code instead of afterwards.

Conclusion

Shipping software without code reviews is like a shipping a book without editorial and proofreading. It takes time, but it's part of the process. So get out there and start reviewing your code!