What most code review comments are actually arguing about

I used to think the worst code review threads were about disagreement over correctness, two people who genuinely believed different things about whether the code worked. Looking back at a handful of threads that actually escalated, almost none of them were that. The code was fine. What escalated was something neither person had said out loud, because neither of us realized we were holding it as a rule until the other person broke it.

The helper function that took eleven comments

A while back, someone on my team added a small formatting helper inside the file that used it, a single call site, maybe six lines. I left a comment suggesting it move to the shared utils package instead. They pushed back: it’s only used once, moving it adds an import and a file to go find later for no benefit. I pushed back on the pushback. Eleven comments later we were both restating the same two positions with slightly more words each time, and if you’d read that thread cold you’d assume we were debating something architecturally important. We were not. I had an unstated rule that anything formatting-shaped belongs in utils regardless of call-site count, because I’d been burned once by three near-identical formatting helpers drifting apart in three files. They had an unstated rule that a shared package is for things actually shared, and a six-line single-use function doesn’t qualify yet. Both rules are reasonable. Neither of us had ever said ours out loud, to each other or possibly to ourselves, until this thread forced it into the open, badly, as a disagreement about one specific function instead of what it actually was.

A smaller version of the same thing happens constantly with naming. Someone names a boolean isValid, someone else prefers hasPassedValidation, and the review turns into three back-and-forth comments about a variable that will never cause a bug either way. That thread isn’t about the variable. It’s about a naming default, verb-first versus a shorter adjective form, that one of you holds more strongly than you realized until you saw the other convention in a diff.

The fix wasn’t better arguing, it was naming the actual disagreement

What changed the helper-function thread wasn’t either of us out-arguing the other on that specific function. It was noticing, embarrassingly late, that eleven comments in over six lines of code meant we weren’t actually talking about the code anymore, and saying so directly: “I think this is actually about when something earns a spot in utils, not about this one function, can we just settle that as a rule and apply it here.” That took four comments to resolve, once it was framed as a default instead of a verdict on this one diff. We picked “shared package once there are two real call sites, not before,” wrote it down in the repo’s contributing notes, and never had that argument again, on that repo, about that specific thing.

The pattern generalizes past that one team. Any time a review comment feels disproportionate to the actual risk of the line it’s attached to, that disproportion is a signal, not noise. A single-use helper function genuinely does not carry eleven comments’ worth of risk. A boolean’s name does not carry three rounds of back-and-forth worth of risk. When the emotional weight of a thread doesn’t match the objective stakes of the code, the gap is almost always an unstated default that just got stepped on, abstraction threshold, naming convention, file organization, how defensive error handling should be by default, and the fastest way out isn’t a stronger argument for your side of the specific line, it’s naming the actual rule being contested and settling that instead.

Writing the defaults down doesn’t end disagreement, it relocates it somewhere cheaper

None of this means teams stop disagreeing once conventions get written down. New situations keep surfacing that the written rules didn’t anticipate, and that’s fine, that’s normal drift for any living codebase. What changes is where the disagreement happens. Instead of relitigating an unstated house-style rule inside a specific pull request, under time pressure, with someone’s actual shipped work sitting in the middle of it, you have the same conversation once, outside any particular diff, and write the answer down somewhere both of you can point to next time. The review comment that used to take eleven back-and-forths turns into a single line: “per the utils rule, this stays local for now.” Nobody’s ego is in that sentence. The eleven-comment version always had somebody’s ego in it, even when neither person meant to put it there, because a diff with your name on it and a rule you didn’t know you held are a bad combination to negotiate in public, one line at a time.