Code Review Without Analysis Paralysis Using the 2-Pass Method

Recently, a coworker asked me how to avoid that feeling of analysis paralysis that can occur when you are doing a code review. I knew the feeling well, but I had not ever stopped to think about how I actually get over it. Upon reflection, I realized I have a method for getting over review-block and getting it done. It even works for self-reviews. When I feel blocked or confused by some code that I’m reviewing, I force myself to review in two passes.

On the first pass of the code review, I simply read all of the code from top to bottom. As I go, I make notes of the questions I have. If I think I don’t have any questions, I might refer to a standard list of questions. For example, I might wonder where a method definition is located, or what a function does. I might realize that I don’t know what range of values is permitted as input to a code path. I make these notes, but I do not deviate from my top to bottom reading of the code. The first pass is simply information gathering and putting the code into my head for later in the code review.

On the second pass of the code review, I try to resolve my questions. I start at the top of my list of questions and I try to answer each in turns. This is when I search through the pull request or even the whole codebase. I track down any references that I need. I find those function definitions. I’m working through my question list from top to bottom. If I can’t answer a question immediately from the code in front of me, I make a note of that on the pull request. If I can’t understand something on the second pass of the code review, I make a note. I don’t let myself stick on any item on my question list for more than about 60 seconds.

Any questions or areas of confusion I have left after two passes become code review feedback. This works well because anything I have questions about after two readings and a minute of research isn’t clear enough. The code either needs to be better structured or better documented. And there’s no shame in asking a question that is easily answered. I don’t feel like a worse programmer when I ask a question during a code review and it turns out it has a simple answer. That’s far better than not asking the question and letting a defect slip by, or agonizing about whether I’m right for thirty minutes before I ask.

The most important thing about this approach is that it is a procedure. It is a checklist. When you are low on energy or focus, it is great to have a procedure to fall back on. Maybe on a great day, you can go much farther than what I outline here, but I know that I can do this even if I am feeling distracted, busy, or anxious. It’s a sort of minimum effective code review. And it catches far more bugs than fretting for half an hour, typing “looks good to me,” and slamming the merge button.

More Posts by Robert Prehn: