So you’re on board with presenting code for others to review—but what the flipside of this?

Code review isn’t always easy to get right. Like any form of communication, it’s often fraught with opportunities for miscommunication and confusion—but working through these challenges for an improved end-result is immensely valuable. We’re here to help.

Consider your ability to support the author before offering a critique

Making regular, bite-sized code reviews a part of your normal development process is a crucial first-step toward making this part of your process. But it’s more than just the first round of feedback that matters. Supporting the developer you’re reviewing is just a critical as your initial technical review.

The depth of your critique should directly correlate with how involved you’re willing to be later in the process.

If you’re offering a simple comment on a quick technical review, be prepared to respond to any follow-up questions that the author may have. But if you’re challenging the core concepts of the entire piece of code, you’re opting in to being involved more deeply—likely until the code is merged.

Deciding if we are capable of providing that longer-term support should be at the forefront of our minds when we intervene and aim to produce a change as well.

Communicate and collaborate properly

Identify what kind of review you’re looking at to determine what you need next—is it a highly complex piece of code that needs additional historical context? Or something that just needs another pair of eyes on it for 5 minutes of technical analysis? Is it delicate, time-sensitive, and will impact the product immensely?

The type of review you’re working with will determine what your next communication and collaboration steps should be—maybe you should meet in person for 15 minutes, chat online for quick clarification, or perhaps you can jump right into the code. The more reviews you do, the more attuned you’ll become to what will help the most.

Pair programming can be the most effective collaboration technique for getting a strong solution. Getting a different point of view inevitably makes the following code review process seamless and much more efficient.

Research the context before requesting changes

Often the hardest thing to accept is that we are not fit to code reviews. This can happen because we’re not that familiar with the stack used, the patterns applied are new to us, or it might be just that the code is too abstract for us.

None of those factors mean you can’t review code.

Research the unknowns—especially before you jump to conclusions. This can be a wonderful opportunity to seek out collaboration or learn something new.  

Besides building your own knowledge, context breeds empathy—and that’s crucial to ensuring you create a safe, open environment for the author. The whole point behind this exercise is to make code better—and that includes supporting the learning and development of the author.

Seek out the underlying train of thought

I can’t tell you how many times, I’ve reviewed code that follows the right practices, shows a super-elevated knowledge of the stack being used, and still, the core idea behind every decision/action totally escapes me.

“What were you trying to solve?” is what I always think next.

Focus your comments on improving and clarifying the intent of each piece of code—in the long-term, that might be the only thing that survives.

Request as many changes you see fit to provide a crystal-clear understanding of every decision point, and make sure these ideas are as near to the code as possible.

Docco (annotated code) is a great tool that lets you add comments than later can be transformed into HTML so we can browse the code next to the comments.

These are the foundational steps of becoming a realistic code reviewer—in part II of this series, we’ll cover critiquing techniques that not only strengthen the final code but the entire team touching it.