Code review: 8 step guide

From my experience, as with any task, you would need a certain level of preparation before you can get started, so that you can make the most efficient use of your time.

Code review is the #1 way of improving code quality.

https://smartbear.com/resources/ebooks/the-state-of-code-review-2018/

It is then, your responsibility to understand what exactly is expected from you, so that you can focus in the right direction.

Reviewing someone else’s code might sound like a trivial task, but believe me, it’s never easy. If you are going to review someone else’s code, there is a certain level of expectation from you. If you or your team doesn’t yet have a code review process in place, or you have been asked to perform code review as an outsider, here are the 8 steps that will guide you through the whole process.

1. Understand the objective of the exercise

You need to understand what is the objective of the code review exercise. Most of the times, you probably know. But if you are unsure, do ask the person who has requested the code review. There could be many aspects of code review.

  1. Low level code review (Line by line review)
  2. High level code review (Architecture and design related)
  3. Code review focusing on security guidelines
  4. Code review focusing on performance guidelines
  5. Code review against specific guidelines provided by the client

Note down the objective of this exercise in the document that you are going to prepare. When you know the exact objective of the exercise, only then you will be able to come up with a plan to meet the expectations. Validate your understanding of the objectives with the development team/requester.

2. Decide the format of code review document

Most of the times, you will already have a pre-defined format to be used for such exercises. By document format, I don’t really mean Word documents. Using pull-request based code review, and adding review comments on GitHub is also a format of recording observations.

On a high-level, each code review comment should have these information:

  1. Issue ID
  2. Observation
  3. File/Class
  4. Suggestions with examples and/or references
  5. Severity (High, Medium, Low)

But if you don’t have any, spend some time to think about the format in which you would be recording your observations, review comments and suggestions for resolution. Get this format reviewed by the requester of the code review. They would always have some important suggestions which you might need to consider that makes sense for them.

Deciding and agreeing upon a common document format not only saves your time, but also makes it easy for the developers to understand and implement your suggestions quickly.

3. Gather project specific guidelines and requirements

Each project or team might have different guidelines. These could be different from the guidelines that you might be working with. Always check with the development team if they have the following guidelines:

  1. Coding guidelines
  2. Style guidelines
  3. Security compliance requirements
  4. Performance requirements
  5. Design requirements
  6. Other non-functional requirements

If there are no project specific guidelines, you should still have your version of these documents that should be used during this exercise.

4. Prepare a checklist of tasks to be done

A checklist of things that need to be done in the code review exercise comes in very handy during the actual code review process. A typical checklist might look like this (not a complete list):

  1. Build and run Unit tests
  2. Check build times and unit test execution times
  3. Run static analysis tools
  4. Check adherence to coding and style guidelines
  5. Code smells checklist
  6. ….
  7. Sensitive data is encrypted
  8. All network calls use “https”
  9. Screen load times are less than 5 seconds
  10. ….
  11. ….

5. Use static analysis tools

Tool-assisted code review is a no-brainer. The first level of code review must be done by using static analysis tools. Some of the issues might not be relevant, but as per my experience, a majority of code review observations are found out by using static analysis tools.

6. Perform manual code review

After you have sifted through all the issues reported by the static analysis tools and collated them, you can now move on to manual review.

For this also, it helps to have a pre-defined checklist of things which you want to go through. It might not make sense to go through all of the code line by line. In some cases, you might only want to review a few files sampled from the 1000s of files. Basically, you should know what exactly you would be looking for.

Manual review process is tedious and time consuming. Here are a few tips that tends to help:

  1. Don’t review code for more than 60 minutes
  2. Check no more than 400 lines of code at a time
  3. Validate your observations against industry standards and peers
  4. Don’t only focus on code. Things like use of data structures, proper use of databases, networking etc should also be reviewed

6(a). Use AI based code review tools (Optional)

There are a quite a number of tools and services that claim to be able to perform AI-based code reviews. Although I haven’t done any detailed analysis on their efficacy, they seem promising. If not right away, a few years down the line, they might completely replace the need of manual code review. Most of them provide a free tier for open source projects. Some of them also provide a free-trial for you to evaluate.

A few examples:

  1. DEEPCODE
  2. embold
  3. AI Reviewer
  4. SOFTAGRAM

7. Review and finalise your report

Go through your final report by reviewing it yourself at least once. If possible, get it peer reviewed as well.

Code review is not about finding faults. It is supposed to be a learning process for everyone involved, even for you as the reviewer. In your comments, make sure to review the tone of the sentences. Try to provide constructive feedback.

8. Walk-through the review comments with the development team

As a reviewer, it becomes your responsibility to put forward your perspective. Additionally, you should also listen to their perspective. During the walkthrough, there might be a possibility that a few changes are required. Be open to discussions and suggestions. If they are relevant, include them in the report.

Code review should not just focus on mistakes. If you happen to notice something which is good, make sure you communicate it to the development team as well.

Conclusion

There are a lot of aspects to the code review process. In this post, I have focused on the important steps that you should be adopting to make this process easy and effective. Let me know if you have any suggestions in the comments section. I would be happy to add your suggestions to this post.

I also found some interesting reads on the topic of code review. I would suggest you to go through them as well.

Further reading

  1. Best practices for Code Review
  2. 9 best practices for code review
  3. Google’s Engineering Practices documentation
  4. Code review guidelines for Humans