Code Review Process
Tags: codereview, productivity, process
Published: 2023-03-24 17:44:17

---
title: Code Review Process
published: true
description: "A robust guide to creating great code reviews for you and the person you're reviewing for."
cover_image: https://curiouslychase.com/img/notes/code_review_process_image.png
tags: codereview, productivity, process
canonical_url: https://curiouslychase.com/notes/code-review-process
---

A friend asked me: "how do you generally approach code reviews? what's your mindset? do you have a checklist?"

Here's my process as it is now (it's iterated over time)!

## My Process for Code Reviews

I do my reviews in 3 **stages** and 3 **passes**.

### 3 Stages

- **Pause** - This is to orient _me_ towards the person requesting review and towards curiosity.
- **Explore** - Review the code, attempting to be curious and noticing any judgment or suggestions that come up
- **Suggest** - Review the code again, adding comments for noticings and suggestions

### Stage 1: Pause
This stage is about orienting, I don't _look at the Pull Request_. 

Here are the steps I take in this stage:
- I **orient myself towards the person** I’m doing the code review for. What do I know about their style? What do I know about their goals? How do I get into a mindset of energetic collaboration.
- I **place myself**. How am I feeling outside of this code review? What have I experienced today? What are my feelings? I put anything that comes up in a note in [Obsidian](https://curiouslychase.com/notes/obsidian) as a container and **attempt to detach extrensic experiences and feelings from the review**. This is important so that I don’t bring it with me into the review)
- **I orient myself towards curiosity**. I want this review to start from curiosity. In tech, so much of what we have been _taught_ matters is **defensive** and **judgmental**. It's not to say there isn't a place to _assess the code_ and _make suggestions_, but the goal of this step is to **reduce my ego as much as possible.**

### Stage 2: Explore
This stage is about going on an adventure in the Pull Request!

In this stage, I take these steps:
- **I orient myself towards the goal.** I read the description. I attempt to rephrase it so I understand it. If any questions come up, I first verify they're not "suggestions disguised as questions" and if they're curious questions, I write them down. 
- **I read the code a first time, starting at the top of the PR.** I try to understand what's happening. I don't make notes. I don't add any comments. I just try to understand _what_ is happening. I hold the code lightly. **I notice places where I hit drag in reading**. Usually drag indicates something isn't clearly. If I notice I hit drag, I write questions from curiosity about the drag. I make notes of if something came up as a noticing, judgment or suggestion but I don't add them to the Pull Request. I will make a note of where I think the execution context is at the end of the read for stage 3.
- **I read the code a second time, starting at the top of the PR.** In the second run, I look for what wasn't clear on a first read. I look to my questions I wrote down. If they're related, I make them as comments. Any comments I add as questions to a review, I start with ❓ so they're easier for me to find later. I review the execution context I guessed on the first pass.

At this point I take a 15 minute break and do something else. 

**Taking a break allows my subconscious to sit with my two passes through the code**.

### Stage 3: Suggest
This stage is where I make suggestions based on my noticings of drag.

Here are the steps to my suggestions:
- **I read the code a third time, starting at the _most obvious entrypoint to the execution context_**. At this point, I've seen the code twice and am oriented towards what it's doing. 
- **I make suggestions where the intent is clear.** I make suggestions in three cases: a fairly obvious security issue, a way to make the code more readable without sacrificing performance, performance benefits that don't reduce readability. In these cases I try to be _really clear_ about what I noticed, which of these buckets I'm making a recommendation for and why I think the recommendation could make it a little better.
- **Notice where someone did _great work_!** I try to notice where I appreciate that the requester has done something that crushes for me and tell them I appreciate it and why. **I think this has 3 benefits.** 1. They get a dopamine hit. 2. I get a dopamine hit. 3. I reinforce what I think matters in a codebase. 

## Some Quick Tips
- **Use [Loom](https://curiouslychase.com/notes/loom) for comments.** Add text to your comments, but also if you can, use a loom here and there and in the comment for the review. **Looms help set emotional context for the person you're reviewing for.**
- **Stay curious.** This code is about a thing someone put effort into. Recognize that they put their energy into it, be grateful for that and ask yourself how you help _amplify_ their efforts instead of snuffing out their energy.
- **Use emoji for comment types and share your heuristic.** Emoji at the beginning of a comment (for example: "❔ I noticed I slowed down when reading this bit of code and I think it's because I don't understand what it's supposed to do, can you give me a summary of what you were trying to achieve with it?"). Emoji makes your comments easily scannable for both of you _and_ helps set context for the comment.
- **Set navigation points in comments.** This is hard to do, but it's always been well received when I do it. If you want to create a narrative about your review, use comment hyperlinks and document them in each comment for **back** and **next**. This helps the person you're reviewing for understand the narrative instead of having to go top to bottom.

## Summary

The most important thing to notice here is that **I attempt to do two passes of a code review before making suggestions**. 

This keeps me curious about what's happening and I think _when_ I follow this, the experience is usually really positive for me and the person I'm reviewing the code for.