Code Reviews: A Straightforward Guide

May 20, 2023 | Rolf Hegrand

Code reviews are an essential practice before integrating new code into the main code base. They confirm that the code performs as expected and adheres to our quality standards.

Good code reviews catch bugs, ensure standards, and foster better code health.

Here are some practical tips on how to effectively review code.

Why Review Code?

  • Catch Bugs: It's important to identify and fix any issues as early as possible.
  • Ensure Standards: The code should meet both technical and stylistic standards.
  • Feedback: Like all things, improvement comes from receiving feedback.

Adopt Efficient Strategies

  • Schedule Dedicated Review Time: Set aside time to review code at regular intervals to prevent delays in the development cycle. I like to schedule a time block in the morning, mid-day, and end of day to maintain consistency. Your mileage may vary, but I find this works well for me.

  • Embrace Smaller PRs: Smaller pull requests (PRs) make the review process easier and lead to quicker turnaround times. When there is less code to review each time, it generally makes it easier to spot potential issues. For larger PRs, I usually try to go over the code with the author, which typically makes it easier to understand.

  • Understand the Context: In the military, soldiers must understand the broader mission to see how their actions fit into the overall strategy. Similarly, in software development, it's important to understand the purpose behind the code. In systems like Jira, tasks are parts of epics, which themselves contribute to larger features. When you understand the bigger picture, you can ensure the code aligns with the overall project goals.

  • Run the Code Locally: While tools like GitHub are commonly used for code reviews, running the code and reviewing it in your Integrated Development Environment (IDE) is advantageous for a few reasons. It's usually easier to read with your usual code theme, you see the context of all the changes (not just the modified lines), and the IDE will usualy highlight potential problems. In turn, it makes it easier to identify issues.

  • Use Conventional Comments: Implement a structured commenting system, such as Conventional Comments, to make the feedback easier to understand.

  • Leverage Modern Tools: For remote complex discussions, tools like Cleanshot X or Loom can be useful. They make it easier to communicate. If you're in the same location, nothing beats talking face to face.

The Bottom Line

Different organizations might have different review processes, but we're still trying to achieve the same goal: bug-free code that meets code standards, and gets better through a review. By reviewing effectively, we make customers satisfied by shipping bug-free software fast.

Code reviews are not just a final check; they're part of your workflow.