Coder Legion - Recent posts tagged programmingblogs

Open the PR your reviewer has not met yet

Fri, 10 Jul 2026 14:02:40 +0000

I got a PR to review recently. Large diff, AI-assisted, touching a module three other features depended on. The description was one sentence. It named the file, not the reason.

I spent fifteen minutes just mapping the change before I could start reviewing. What the intent was. Where the risk was. Which files mattered and which were noise.

Somewhere in the middle of that fifteen minutes, I thought: I have done this to someone else.

The author forgets what the reviewer does not know

When you write the code, you carry everything.

You know why the module was split. You know what you tried before landing here. You know which section you shipped with a quiet doubt. You know the edge case that is technically handled but not properly tested.

Then you open the PR.

And you write the description from that place. From inside the full context, for the version of you who already knows. Not for the reviewer who is about to walk in without any of it.

"Refactored service layer."

"Updated config handling."

"Fixed issue with auth module."

These are descriptions written from memory, not for someone without it.

AI widened the gap before I noticed

There is a specific unease I have felt looking at my own PRs a couple of days after raising them.

The code is fine. The tests pass. But I cannot reconstruct why I made the choices I made. The work was AI-assisted, the diff was large, and I had moved fast. Moving fast and understanding deeply are not the same thing.

I opened one of those PRs recently. A refactoring pass. I tried to read it as a reviewer. I had a question I could not answer from the description. The answer existed. It was in my head when I wrote the code. It never made it into the PR.

That was the moment I realized the description was not a summary. It was a test.

Write it for the version of you who will review this in three days

That realization changed how I write descriptions.

Not a template first. A question first: if I came back to this PR in three days knowing nothing, what would I need to read before opening the diff?

I sat with that question long enough to realize I needed a structure. Not something I could skip when moving fast. A concrete template I would follow before any non-trivial PR opens. I built it, tested it across refactoring passes, AI-assisted features, and larger architectural changes, and refined it until it held.

It has six parts.

Intent - not what changed, but why this PR exists and what problem it is solving. One paragraph. If you cannot write it clearly, stop. The PR is not ready to open.

Major changes - the decisions that touch architecture, existing behavior, or anything a downstream system depends on. This is where the reviewer needs to slow down.

Minor changes - the cleanup, the renames, the noise. Named separately, so they do not sit next to structural changes and get equal weight.

Impact - what features, modules, or systems this PR touches. The blast radius, stated plainly. Not documentation. A map.

Evidence - what was run, what was walked through manually, what coverage looked like. Not to satisfy a process. Proof that the author did the work before asking someone else to do it.

And the one most descriptions never reach: what I was uncertain about.

Naming uncertainty is not weakness. It is direction.

When something works but I cannot fully explain why, I say so. Directly, in the description.

For the reviewer, it is a targeting signal. They know where to read closely and where to move. Without it, they distribute attention evenly across a diff that does not deserve even attention.

Writing it is a checkpoint. If I cannot name what I am uncertain about, I have not thought carefully enough about my own code. That line has stopped me from opening PRs that were not ready.

The description is not the last step before review. It is the last step before I know whether the PR should open at all.

The reviewer who opens this has not met your code yet

When I compare the PRs I was proud of shipping against the ones that came back with questions, the difference is rarely the code.

It is the description.

A reviewer who understands your intent from the first read spends their time on the hard questions. A reviewer who has to reconstruct your intent spends it on the easy ones. Asking what things are instead of whether they are right.

Part 1 of this series argues the reviewer's side of the same problem. If you arrived here first, it is worth the detour. The argument there: reviewers now need to look past surface correctness and find intent. But intent does not appear on its own. Someone has to put it there before the review begins.

Write it for the reviewer who has not met your code yet.

Write it as if you will not be there to answer questions.

Write it as if the next person to read it is you, three days from now, with no memory of writing it.

If it holds up, the PR is ready.

Review the code that does not exist yet

Fri, 10 Jul 2026 14:02:11 +0000

I have reviewed code for years, and for most of that time the habit was simple. Open the diff. Read every line. Find what is wrong. It worked, and it worked for a boring reason: the diffs were small because writing code by hand is slow.

The diffs are not small anymore.

A pull request now arrives with twenty files in it, built in an afternoon, more code than I could have written by hand in a week. The old habit does not fit a change that size. It bends, then it breaks. So I had to ask a question I had spent years quietly avoiding.

What is a code review actually for?

The first thing I lost was the point

Few years ago, I was the senior reviewer on a small team. I took the role seriously. Maybe too seriously.

I opened each pull request hunting for faults. Indentation. Naming. A function that could be three lines shorter. A pattern we had agreed not to use. I found them. I was good at finding them. It felt like the job. Every comment was proof that I had been paying attention.

One day I left seventeen comments on a frontend pull request.

It was a CSS-heavy change, and CSS changes are hard to review on a diff. The developer had not followed the UI design standards we had set as a team. Almost none of them. So I went through it line by line and marked every single thing I could find. I sent it back.

I felt like a jerk afterward. But I also thought I had done the right thing.

Then I looked at what I had actually been reviewing.

I had read every line. I had not read the work.

The developer had built exactly what was asked. The feature worked. It was a clear, self-contained piece of UI. And I had spent the entire review arguing with the formatting, as if the formatting were the thing we shipped to users.

That is the day I started reviewing code for a different thing. Not for what it does the moment it lands. For what someone will do to it next.

This is not an argument for shipping mess. I still send back work that buries its intent under careless code, because code that is hard to understand is hard to change, and hard to change is where the real cost lives. The difference is that I keep room for an exception now. I do not treat every rule as a wall I am paid to defend.

A rule is a tool for protecting intent. When I started treating the rule as the point, I forgot what it was protecting.

I had been reviewing the rules. I had stopped reviewing the work.

Then the diffs got faster than I could read

For a long time that lesson stayed quiet. Useful, but never urgent.

Most pull requests were small, because authoring was slow, and a reviewer could keep pace with an author without much strain. One person wrote for a day, another read for an hour, and the arithmetic worked. The whole practice of review was built on that arithmetic.

Then people started building with AI.

Now a change lands with twenty files. Different layers, different concerns, all in one push, all produced faster than I have ever produced anything in my life. And my first thought is almost always the same.

This is over-engineered.

Sometimes it is. Often it is not. The instinct fires not because I have judged the design, but because the sheer size of the thing is unfamiliar, and unfamiliar reads as wrong. The honest problem is mine. I could never have written that much code in a day. Reviewing it in a day was the part that unsettled me most.

The bottleneck moved.

AI made writing code cheap. It did not make reviewing it cheap.

Authoring used to be the slow and expensive step, and review was the quick sanity check at the end. That order has flipped. The code now arrives at almost no cost. The judgment about whether the code is right costs exactly what it always did, because judgment was never the part AI made faster.

The bottleneck did not disappear. It moved onto my desk.

So I changed what I look for first

If I cannot read twenty files the way I read two, then reading every line first is the wrong opening move. It is slow. Worse than slow, it is misaimed. It spends my sharpest attention on the smallest things, early, while the largest things wait, unread.

So I stopped starting with the code.

I start with intent. What is this change trying to do, and does the shape of it match that goal? Does the structure tell the same story the description promised? Only after those questions do I care how any individual line is written.

This is what I mean by reviewing the code that does not exist yet.

The diff in front of me is temporary. It is the least permanent thing in the whole exchange. Someone will change it in six months. Someone will debug it at two in the morning with half the context I have right now. Someone will push it past the scale the author ever imagined, and watch it fail in a way nobody designed for.

Those people are who the review is really for. Not the author, who already understands the change. Not me, who will forget it by next week. The stranger who inherits it.

The diff is what changed. The future is what I am approving.

The order is the method

Over time my questions settled into an order, and the order turned out to be the whole point. It is not a list to tick off until every box is full. It is a path, and most of it happens before I judge a single line.

It runs like this.

What is this trying to do? → How did they solve it, and would I have solved it differently? → What trade-offs or unknowns are sitting in plain sight? → Does this actually improve the thing, or is it added weight, a time bomb waiting for the day nobody is watching? → Am I sure?

Each question guards against a different failure.

The first keeps me from reviewing a change I do not understand. The second keeps me honest about the difference between a real problem and my personal taste. The third is where most of the danger hides, because the dangerous parts of a change are rarely the loud ones. The fourth is the one that only gets answered in production, usually later than you wanted. And the last question, am I sure, is the one I added for myself, because the worst approvals I have given were the confident ones.

Only after all of that do I open the files and read them line by line, with no mercy.

Look at where the strict part lives. At the very end.

Everything before it is about understanding the work and arguing with my own judgment. The line-level pass is not the review. It is the last step of the review, and it only earns its place once the rest has cleared.

You earn the right to nitpick. You do not start there.

This is not permission to ship slop

I can hear the objection, because I would raise it myself. Does intent-first mean a lower bar? Does it mean waving through sloppy code as long as the idea behind it is clear enough?

No.

The strict pass still happens. It happens last instead of first, but it happens, and nothing on the list above is a substitute for it. Intent-first is not standards-free. It is the same standards in a better order.

And there is a newer risk that makes the order matter more, not less.

Volume hides intent.

A twenty-file change can be correct in every single file and still be dangerous, because no one person can hold the whole of it in their head at once. The failure is not in any one line. It lives in the space between the files, in an assumption made in one place and quietly broken in another.

About nine months ago a pull request landed on my desk with forty-five files in it. I was lenient. I skimmed the parts that looked safe, approved what looked obvious, and moved on.

Six months later the APIs started creating duplicate transactions in production. We could not find the root cause. The file at the center of the problem had grown to over five thousand lines of code, and the issue was buried inside of it.

It took a long time to dig out. That change had looked fine in every file I checked. I had just never asked whether it was wise.

Reading for intent is how I catch that before it merges. A checklist cannot — it looks at each file alone.

A checklist can tell me the code is correct. It cannot tell me the code is wise.

The fear I started this with never left me. I have just stopped fighting it, and started letting it sharpen the right questions.

I did not learn to read faster. I learned to read in the right order.

What I actually approve

This is what I think a review is.

I am not the spell-checker. I am not the gate that catches a missing semicolon or an unused import. I am the person asking what this change will do to whoever inherits it, long after the author and I have both moved on.

That question works at every level of experience, because it is a question and not a rule. A new engineer can ask it on their very first review. A senior engineer asks it on their thousandth. Nobody is too junior to wonder what happens to this code in a year. Seniority does not exempt you from the question.

And it has a limit I have started to feel.

A reviewer can only do so much when the pull request is fighting them. If the intent is buried, if twenty files arrive with no story to tie them together, if the risky change is hidden in the middle of a dozen safe ones, then no amount of patient reading will rescue the review. The reader cannot supply a clarity the author refused to provide.

Which means half of this problem was never the reviewer's at all. It belongs to the person opening the pull request. That is the other half of the story, and it deserves its own piece.

Review is not about the code in front of you. It is about the code that comes after.