The Code Review Comment I Stopped Writing, and What I Write Instead

For about four years, one of my most common code review comments started with the words "Why didn't you just". Why didn't you just use a map here. Why didn't you just put this in the existing helper. Why didn't you just return early.

I thought these were gentle. They were questions, after all. Then a junior engineer on my team, a sharp guy named Pradeep, told me during a one-on-one that he had started dreading my reviews. Not because they were harsh, but because they made him feel like the obvious answer had been sitting right there and he had been too slow to see it.

The word "just" is doing a lot of damage

When I went back through my review history, I counted 63 comments with "just" in them over six months. In almost every case, the thing I described as "just" doing was something I knew because I had spent years in that codebase. It was not obvious. It only felt obvious to me.

The phrase also hides the actual question. "Why didn't you just use a map" could mean I think a map is faster, or that I think it is more readable, or that I am genuinely curious whether there was a reason. The author has to guess which, and people under review tend to guess the worst version.

What I write now

I settled on three patterns, and I use them on purpose.

• "I would consider X because Y." This states a suggestion and a reason in one go. If the reason is wrong, the author can say so.
• "Is there a reason you chose X over Y? I ask because Z." This is for when I am genuinely unsure. The "I ask because" part matters. It tells them what I am worried about.
• "Nit, take it or leave it." For style things that do not matter, I label them clearly. Unlabeled nits feel like blockers.

I also started leaving at least one comment per review that is not a request. Something like "This test name made the intent really clear." It costs nothing and it changes how the rest of the comments are read.

The numbers moved, a little

I did not run a controlled experiment. But I did look at our pull request data before and after. My reviews used to average 2.6 rounds before approval. Six months after the change, it was 1.9. The median time from first review to merge dropped from about 26 hours to 17.

Part of that is probably because the reasons in my comments let people fix things once instead of guessing twice.

It is not about being nice

I want to be careful here. This is not a story about softening feedback until it says nothing. I still block pull requests. I still ask for changes that people do not love. The difference is that every comment now carries the reasoning, so the author can push back on the reasoning instead of on me.

Pradeep, for what it is worth, now reviews more of my code than I review his. His comments are better than mine ever were.