Code Review Best Practices You Can’t Miss

When a code review is performed well, it can strengthen relationships within a team, improve software, and feel natural.

But without due care and attention, code review can be stressful, lead to resentment within the team, and result in a codebase that feels like it has more politics in it than business logic.

In this article, we’ll cover five main areas of conducting a great code review. By the end, you’ll be primed with enough information to make sure code reviews on your team is a positive experience all around.

What is code review?

Code review is the act of one person manually reading through another person’s code, looking for errors and opportunities where there could be an improvement made.

It has become standard practice in many modern software development teams.

Code review can take place in person, with the reviewer asking face-to-face questions of the code to the person who wrote the code, or it can happen entirely remotely, perhaps with someone sharing their thoughts a day or two after the code has been written.

Why code review is important?

Code review between peers acts as a second pair of eyes. Often, the fresh perspective that another developer brings to code can help think of edge cases that the original developer didn’t consider.

Code conventions and the naming of methods and variables can also be brought into question. Something that sounds entirely understandable to the original author might seem terrible to someone reading it for the first time.

From a business perspective, we do code review because reviewed code should contain fewer bugs, have fewer security vulnerabilities and will provide more value to the customer.

From a personal development perspective, we do code review because we can learn from each other. Not just better development techniques but also better communication skills as we have to justify our coding decisions.

When should code review be done?

There are two times when code review is most effective.

#1 When a ticket gets completed

When a developer has finished working on a body of work and thinks it is ready to be put online for the world to see, it’s a great opportunity for code review. At this time, another opinion can help spot things the original developer missed.

#2 When someone is struggling

Midway through a ticket, a developer might decide they need some help. Performing a code review at this stage can help a second developer gain the context they need to advise on a way forward. Sometimes even the act of preparing the code for review is enough to unblock the person who was stuck.

Who should do code review?

Code review is generally done by a peer with a similar tech background to the person who wrote the code. For example, if the code is Python, then another Python developer should review the code.

Sometimes you may wish to be more specific in who is involved in a code review, like in the following cases:

  • When you need a specialist to approve your code, such as when you have questions about performance, a performance specialist on your team should be asked to review.
  • When you want the code to be understood by lots of people, you could ask a developer who doesn’t know Python to review your Python code to ensure that it’s easy to understand even without expertise in the language.
  • A developer with a vested interest in what is being made or changed might request to be part of the review.

How to do code review?

Code can be reviewed in person or remotely.

Comments or questions that arise should be recorded against the code being reviewed, even if the review is happening in person. This allows people looking over the code in the future to see conversations that were happening. Tools like Github make this process easy.

When conducting code review, you should be looking to answer several questions:

  • Does the code complete the criteria set out in the ticket?
  • Is the code clear and understandable?
  • Does the code match up to our team’s quality standards?
  • Does this code introduce issues we haven’t thought of?

Each team will have different criteria for code review, if you’re doesn’t, here are some technical points you should check.

Whatever your criteria, when reviewing someone’s code, it is essential that you:

  • Be kind. Having your code reviewed by someone else can be incredibly stressful for some people, negatively commenting on code doesn’t help anyone.
  • Be consistent. If you would raise something as an issue with one developer, raise it with all developers.
  • Take your time. Skimming over the code and giving it a quick thumbs-up is a wasted opportunity to learn and to improve the codebase.
  • Ask lots of questions. If you see something you don’t understand, don’t be afraid to ask.

Google recently shared an article on respectful code reviews, that shares a lot of great insight into some dos and don’ts of code reviews.

How does your team do code review?

Does your team have an established code review practice? We’d love to hear about it @TextExpander.