Josh Martin Dev

Josh Martin Dev

Code Reviews and When to Use Them

Code Reviews and When to Use Them

Subscribe to my newsletter and never miss my upcoming articles

Code reviews allow you to ensure you're putting forth the best product possible. They're very beneficial because they help:

  • Detect and remove defects.
  • Ensure requirements are met.
  • Identify potential improvements (code syntax or efficiency for example)
  • Determine progress in a project
  • Reduce development time
  • Reduce testing time (because of less defects).

It is important to know that the sooner a defect is found, the cheaper it is to fix. For example, if a defect is found during the development stages before it hits the Quality Assurance team, you're reducing the amount of time QA needs to spend on that particular issue. A more extreme example would be a defect goes undetected and makes it into a production build. What could have been a quick and simple fix in earlier stages of development has now become a high risk fix because you need to apply the fix to the production environment.

But, what is a Code Review?

A peer review is where you get eyes on your code to receive feedback and suggestions on how to improve your written code. It is absolutely something many dread. It's hard to have eyes on something you've created and listen to feedback, no matter how harsh, and apply it to what you've created.

No matter your experience level, you need to always remember a code review is in place to ensure quality in the product and, most importantly, quality in the programmer (you!). Try not to take offense to any suggestions -- Simply evaluate the suggestion and either agree or disagree and express your opinion to either apply that suggestion or why you don't feel it should be applied.

Informal Reviews

If you're part of a small development team, this is probably the type of code review that will likely happen. Sometimes called a "Desk Check," an informal review is a just a casual meeting between two developers to review written code or functionality.

With a desk check, there isn't typically any advanced planning or preparation. Typically, these are started by saying, "Hey Shannon, can you come look at this code with me?" and then Shannon comes over to look at code. Welcome to a desk check.

Because there is no formal planning or preparation, these types of reviews are not fully productive. Sure, you're going to uncover some things, but there will be things that are missed because you just aren't thinking about it.

Instead of doing these impromptu, I recommend that you try to formalize the desk check/informal review. Make it more... formal! You can do this by scheduling time to do a review with your coworker(s) and giving your coworker(s) a little time prior to the meeting to review the code. To make it really impactful, formulate a list of things to check against to ensure your code base meets the standard of your company.

Formal Reviews

Formal reviews are pretty similar to informal reviews except there is more structure and more people participating. One of the biggest benefits to a formal review is that you can bring together senior developers and junior developers which allows junior developers to see how a senior developer approaches situations. On the flipside, the senior developer can be reminded of more simple solutions to problems. Juniors are eager to learn and Seniors can sometimes overcomplicate things that can be simple.

Another huge benefit to formal reviews is that because you have multiple sets of eyes on the code, you will have multiple people who understand this area of the code or product. There is nothing worse than only 1 or 2 people understanding how something works only to have them leave and the remaining team has to devote time to understanding that area without any guidance.

Each formal review should follow these guidelines:

  1. Limit the review to 3 and 5 people.
  2. Everyone should have time to prepare (and they should) for the meeting. Preparing should be no more than 2 hours in time-- even so I feel that 2 hours is pushing the limit.
  3. The review meeting should be less than 2 hours.

The focus for the review should be a small piece of the overall software. We aren't trying to review the entire code behind a given piece of software. To help get everyone up to speed on what the given code does, provide context on how this code interacts with the rest of the software by presenting a quick walkthrough. Regardless, by narrowing the focus, you will have a higher likelihood of uncovering errors.

When to Review

An informal review is informal. These types of reviews happen fluidly and don't have a set time. I do, however, recommend that you set some time aside to review code as it is completed, though.

For a formal review, there is a process and it typically goes like so:

  1. Developer will write code and feel they have a finished piece of work.
  2. Developer informs the project leader that code is complete and ready for review.
  3. Project Leader will contact a Review Leader, who evaluates the code for readiness, creates copies of product materials, and distributes them to 2 or 3 reviewers for advanced preparation.
  4. Each reviewer is expected to review the code making notes and becoming familiar with the work that was created.
  5. Project Leader schedules a review meeting and establishes an agenda.

What Happens During the Review

Typically what happens is the code is reviewed by all meeting attendees and suggestions are made. By the end of the meeting, the group will have a decision to make with 3 outcomes:

  1. Accept the written code as written with no modifications. (Rare)
  2. Accept the written code provisionally with minor modifications and no additional review (Common)
  3. Reject the written code due to severe errors and another review will be required (Uncommon to Common)

There is a lot more that goes into the meeting, but that is a topic for another day.

NOTE: This is my own opinion. It does not reflect the views or represent the voice of my past, current, or future employers.