Code review comments that land: examples, rewrites, and severity

Search for code review comments examples and most of what you find is etiquette: be kind, be constructive, assume good intent. All true, and all useless at the keyboard, because kindness is not a technique. What actually separates a comment that lands from one that starts a fight is craft you can practice: what the comment points at, whether it carries a reason, and whether the author can tell how much you mean it.

Point at the code, not the coder

The word “you” is the most dangerous word in a review. “You forgot to handle the timeout” and “this path swallows the timeout” describe the same line, but the first keeps score and the second reports a fact. Facts invite correction; verdicts invite defense. This is not about sparing feelings so much as keeping the discussion attached to the diff, where it can be resolved by editing code instead of by winning an argument. If a comment would read differently with the author’s name removed, rewrite it until it would not.

Give the why, not just the instruction

“Use a Set here” forces the author to either obey without learning or push back without information. “A Set makes the dedupe linear and says intent; the array scan goes quadratic on large inputs” is the same request, and it teaches. The why also serves the third audience every thread has: people reading it later, deciding whether the advice applies to their case. An instruction without a reason expires with the thread. A reason compounds.

Say how much you mean it

Half of review friction is severity ambiguity: the author cannot tell whether your comment blocks the merge or is a passing thought. Conventional Comments fixes this with prefixes: issue: for problems that need addressing, question: for genuine uncertainty, nit: for optional polish, praise: for patterns worth keeping. The labels cost nothing and make every comment self-triaging. They also keep you honest: typing nit: in front of a comment is a small forcing function to admit it is one, which connects to the larger argument that nitpicks should be automated or marked optional rather than delivered as ambiguous demands.

Code review comments examples: before and after

• Before: “Why would you do it this way?” After: “question: is the retry loop intentional for the non-idempotent case? If this POST can fire twice, we may need an idempotency key.”
• Before: “Wrong. Breaks on empty input.” After: “issue: parseCsv throws on a zero-length file because the header split fails. An early return with an empty result would match how loadJson handles it.”
• Before: “Rename this.” After: “nit: fetchUser also writes the cache; loadAndCacheUser would say what it does. Fine to skip.”
• Before: “This is not how we do error handling.” After: “issue: this catch block drops the original error, so the alert will fire with no cause attached. Our wrap-and-rethrow pattern is in errors.md; happy to pair on it.”

Every rewrite is longer. That is the cost: a sentence of reason and a severity label. It is cheap compared to a deadlocked thread or a colleague who quietly stops asking you for review.

Praise that teaches

Praise in review is not decoration, and it is not the empty approval that makes LGTM culture so corrosive. Specific praise is training data for the team: “praise: making the cursor opaque here is exactly right, it stops clients from depending on the encoding” tells the author what to do again and tells every other reader what good looks like in this codebase. Generic praise evaporates. Specific praise replicates the pattern.

When a thread deadlocks, leave the thread

Microsoft’s research on modern code review found that understanding the change is the top challenge reviewers face, which explains why long threads so often talk past each other: the participants are working from different models of what the code is doing. Three rounds of written back and forth is the practical limit. After that, take it to a call or a whiteboard, converge in minutes, then come back and record the outcome as one final comment. The record is the part people skip and the part that matters: “discussed offline, keeping the queue, adding a lag metric” turns a private resolution into context the next reader inherits for free.