Reviewing code you’re not familiar with

We’ve all had to do code reviews on bits of code we weren’t very familiar with. Whether it’s part of the application you haven’t worked on before or a new hire who’s looking at the code-base for the first time, it’s never obvious what to look for, how to determine if the implementation details are bug-free, or how in-depth you should go. The natural instinct, at least for me, is to gloss over the higher-level concepts and look only for obvious mistakes in the implementation details. So how do you get up to speed quickly, figure out what needs attention and doesn’t, and find potential issues with the implementation? As it turns out, a lot of it relies on what the person creating the code review makes available to you as the reviewer.

For that reason, let’s start by having a look at what the reviewee can do to help the reviewer. One of your goals when asking for a code review should be to give the reviewer as much contextual information as possible. And if you’re the reviewer, you should probably consider asking for these details if they weren’t provided. It’ll go a long way to give the code review the attention it deserves.

• Organize a time-boxed 5 minute tour of what you did before submitting a code review. The goal is to give the reviewers an overview of what they’ll be looking at so they can focus on the implementation details and reduce the number of questions they’ll have if they’re not familiar with the part of the solution you coded.
• This tour should give an overview of the problem, how you solved the problem, any alternatives you considered, and general structure of the solution.
• Mention any frameworks that you used, and any issues that you may have had with them (versioning, deprecations, dependencies, etc.).
• Try and plan this tour for a time when you’ll least impact the context switch time for reviewers, such as just before or after lunch.
• Add as much detail to the code review as possible, which will help the reviewer get a better understanding of the code.
  • Clear explanation as to what was done and why, linking back to the story or task related to the code you just wrote.
  • Any paradigms used in the solution, such as a design pattern or architectural concept that was implemented.
  • Any areas where you want specific attention to be brought to.
  • Identify any issues or edge cases that you know you didn’t address and why. Otherwise these may come up at a time that is distracting to the rest of the code review.
  • Make sure reviewers read all the information you just took the time to provide them. It’ll go a long way to getting them the context they need to perform a proper review.
  • Finally, include the URL to the repository/branch for quick checkout. Some tools will do this automatically but others don’t. You want to do everything you can to avoid reviewers getting to this final step but there are some people who will still want to checkout the code directly no matter what.
• Keep the entire review to a reasonable size.
• This relates back to the Single Responsibility Principle, but applied to a code review. If the code review only covers a single task, it’ll be easier for the reviewer to understand what’s going on and provide meaningful feedback. For example, if you’re building an online store, a code review for the entire purchase component would probably be too big, but if you just review the credit card purchasing part of the system, it’ll be much smaller and more manageable.
• Make sure to only include the commits you need to be reviewed. It’s easy to accidently include commits that you don’t need from another task or developer and these will only cause noise and distraction from the core of the code review.

Let’s switch over to the reviewer’s side. In this case, you have a responsibility to provide valuable feedback to the person who asked for the review. To do that, you need to be able to understand what you’re looking at quickly. There are a few steps you can take to that effect:

• Make sure you have at least 30 minutes to dedicate to the review. Depending on the size of the review, it may take less than that but you want to allow enough time to focus on the problem being solved, and have a good understanding of what might need to be tweaked.
• You should start by reviewing all information that was provided by the reviewee. Even if you were working on the same bit of code recently, it’s possible you aren’t aware of some business rules or technical issues that may have required a change with the implementation. Take the time to read through the related story or task as it’ll have the most up-to-date information as to what is being solved in this code review. If you feel there’s something missing to have the full picture, you should ask the reviewee for it before going any further. It’ll save questions and time later on.
• If you’re using a tool for code reviews (and you should be), increase the number of lines shown before and after each change. It’s often difficult to see what a change to a single line might have as impact in the method or class it’s in, and viewing a few lines before and after will provide that little bit of extra understanding that might make you notice a potential issue.
• If a change doesn’t seem to make sense, have a look at the commit message and history. Hopefully, it will have something to indicate as to why a change was made. Also, each commit should have the related ticket in its description, which can also provide some additional context to the change. Don’t assume something is a mistake when in fact it’s due to your misunderstanding of what was trying to be accomplished.
• If you still can’t figure something out, it’s best to reach out to the person directly before writing any comments in the code review. Adding comments for issues that aren’t real problems will just generate noise and reduce the quality of the code review.

To summarize, a code reviewer who isn’t very familiar with the code base relies heavily on the reviewee to provide enough context and information related to the change. That just means you need to make sure the people creating the review understand why adding these extra details to the review are very important.

If you have any other tips for how to understand a code review on code you might not be familiar with, feel free to add them to the comments below!