The Code Review Comment I Stopped Leaving

For the first few years of reviewing code I wrote a comment that looked helpful and was close to worthless: "This could be more efficient."

It is technically true most of the time. It is also unactionable, unmeasurable, and it puts the burden of deciding whether it matters onto the person least equipped to make that call — the author, who now has to guess which of fifty possible efficiencies I meant.

Why it fails

A code review comment needs three things to be useful: a specific observation, a reason it matters, and a suggested direction. That comment has none of them.

It also has a hidden cost. The author reads it as "the reviewer thinks I am not good at this," because there is no content to engage with — only a judgement. They either ignore it (and learn that review comments are noise) or gold-plate the change (and ship something more complex for no measured benefit).

What I write instead

Three replacements, depending on what I actually observed:

When I have measured something

"This loop calls $post->category inside it. With 9 posts that's 9 extra queries — the index page currently does 3 total. Adding ->with('category') to the query keeps it at 3."

Specific, measured, with the fix. The author can verify it in thirty seconds and the conversation is about a number rather than a feeling.

When I suspect something but have not measured

"I think this is O(n²) in the number of tags, but I haven't profiled it. Do you know what the realistic upper bound on tags per post is? If it's under 10 I'd leave it."

This is honest about the uncertainty and invites the author's context, which I do not have. It also gives them permission to leave it alone — which is often the right call, and one my original comment never allowed.

When it is a preference, not a problem

"I'd normally extract this into a scope, but it's only used here so I don't think it's worth it. No change needed — flagging it in case you were planning to reuse it."

Saying explicitly that no change is needed, and why I mentioned it anyway, removes the implicit demand. It also distinguishes "I would do it differently" from "this is wrong," which are very different claims that most review comments blur.

The distinction that matters

Almost every unhelpful review comment comes from collapsing three different statements into one:

| Statement | Requires a change? | Needs evidence? |
| --- | --- | --- |
| This is wrong | Yes | No — correctness is binary |
| This will cost us later | Yes, eventually | Yes — a number or a plausible scenario |
| I would do it differently | No | No |

The first is a bug report and should be stated plainly. The second is a trade-off and needs evidence, because otherwise it is the third in disguise. The third is a preference and should be labelled as one.

Most reviewers are confidently writing the third and hearing it as the first.

What changed in the teams I have worked with

Once I started labelling my comments, two things happened.

The number of comments went down, because a lot of what I used to write turned out to be preference, and preferences do not need to be said out loud.

The number of changes made went up, because the comments that survived were specific enough to act on and were not competing with thirty other vague suggestions for the author's attention.

The habit

Before leaving a comment, name which of the three it is. If it is a preference, say so and move on. If it is a cost, bring a number or a scenario. If it is a bug, say it directly and skip the softening.

It takes about four extra seconds per comment and it is the highest-leverage change I have made to how I work with other engineers.