Code Review

Code used to go straight into the main line without anyone else looking at it, and that failed in two directions. The first is that mistakes are least visible to the person who made them. After three hours inside the same file, you stop seeing what you left out. The second is that only one person on earth understands the code.

Pagedeck lived through exactly that. Theo built the payment logic alone and it ran fine for three months. Then charges on one card type started arriving late, and because nobody else had ever opened that file, the fix sat untouched for the four days Theo was on vacation. The missing owner was a bigger problem than the bug.

Code review exists to close both gaps in one step. Putting a person in the path before a merge buys you a check, but it also produces a second person who has read the code. That second effect is the one that lasts.

A change passes through six stages between being submitted and landing on the main line.

1. The author finishes work on their branch and asks for review. A branch is a separate line of work split off so the main line stays untouched. The request carries a written description of what changed and why.
2. Reviewers are assigned, usually one or two, never the whole team. Past three people everyone assumes someone else will take it, and responses get slower rather than faster.
3. Automated checks run first. A linter flags rule violations like indentation and naming, and unit tests confirm that individual functions still behave the way they did. The point is to spend no human attention on anything a machine can catch.
4. Reviewers read the changed lines and leave comments. Comments attach to specific lines, so nobody has to describe where in the file they mean.
5. The author revises, or explains why the code stays as it is. Not every comment has to be acted on.
6. A reviewer approves and the change merges. Most teams configure the repository so that nothing reaches the main line without an approval.

Reviewers are looking at three things: whether the code does what it was meant to do, what breaks when an unusual input arrives, and whether someone opening the file six months from now can follow it. The first two are about how it behaves today; the third is about how long it stays worth repairing.

Comments should carry a strength marker. Separating "this breaks" from "I'd suggest" from "just curious" with a short prefix tells the author what to handle first. When "this crashes on null" and "I'd have named this variable differently" look equally weighty, the author treats both as instructions and starts with the smaller one.

Keep a single review under roughly 400 changed lines. At 200 lines a reviewer reads line by line; at 1,200 most people read the first hundred carefully, skim the rest, and approve. The bigger the batch, the faster it passes and the less it catches.

Pick two reviewers with different jobs: someone who already knows the area, and someone likely to work in that code later. The first one checks the change against everything they know about how that part behaves, and the second one walks away carrying a map of code they had never opened. Seniority is not the sorting rule. Someone two months in who writes "I can't tell why this part is needed" has produced a real review finding, because code that needs a verbal explanation to make sense is itself the finding.

The timing target is within a day. Pagedeck's agreement is that anything posted in the morning gets read before people leave. When review lags, the author starts the next task and then has to climb back into work they have already left behind. The branch ages too. Merge after a day and a merge touches two or three overlapping lines; leave it a week and the main line has moved enough that conflicts arrive by the fileful.

The exception is incident response. When the service is down, the fix ships first and the review happens the next morning. A team that reaches for this exception often ends up with a process that exists in name only.

"Could you take a look at this review? Not urgent — any time before tomorrow is fine."

Attaching a deadline so the reviewer knows whether to stop what they're doing right now.

"This review is too big. Could you split it in half?"

At this size it can't be read properly, so send back something that can be.

"This one's just a suggestion, so feel free to skip it. I'll approve now."

Leaving a comment without blocking the merge.

At Pagedeck, review is how the engineering day opens. Theo reads the incoming requests before picking up any work of his own. His own changes are sitting in someone else's queue at the same time, so clearing other people's reviews first is what keeps his own from stalling, and the order sorts itself out without anyone scheduling it.

Mia watches the same step for a different reason. When a schedule slips, the cause is sometimes not how fast engineering builds but how long reviews sit. If work finished on Tuesday and the approval landed on Friday, three days passed with nobody working on it. When that gap stays wide across several cycles, Mia's first move is to fix the review rhythm rather than to ask for more people.

The most common misreading is that review is where your mistakes get pointed out. On the receiving end it looks like red marks on your own work, so the feeling is easy to arrive at. In practice it is closer to shared ownership: the approver takes on part of the responsibility, so when that code causes trouble later the author isn't the only one in the room. In teams where the misreading sticks, people avoid being reviewed by quietly batching changes into bigger drops, or they approve without commenting. The process survives and the benefit disappears.

Reading approval as proof there are no bugs is the other one. The approval badge looks like a quality guarantee, which makes the assumption natural. But reviewers read code rather than run it, so only the problems visible on the page get caught. Errors that appear under one specific condition, or slowness that shows up once the data grows, are not visible by reading. Teams that treat review as the final gate tend to thin out their testing and verification stages, and within a couple of quarters the share of failures first discovered in production climbs noticeably.