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.
The short answer: A review comment lands when three things are true: it points at the code rather than the person, it carries the reason and not just the instruction, and its severity is explicit so a nitpick cannot impersonate a blocker. Add genuine questions when you do not understand intent, and specific praise when you see a pattern worth spreading, and most tone problems disappear without anyone trying to be nicer.
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.
Frequently asked questions
How do I write code review comments that do not offend?
Comment on the code, not the coder. "This connection never closes" lands; "you forgot to close the connection" keeps score. Give the reason with the request, mark severity honestly so a nitpick cannot masquerade as a blocker, and ask a genuine question when you are unsure of intent. Most defensiveness in review is a reaction to verdicts delivered without reasons.
What are Conventional Comments?
A lightweight convention for prefixing review comments with a label such as issue:, question:, nit:, or praise:, so severity travels with the words. The author can tell at a glance what blocks the merge and what is optional polish. It costs nothing to adopt, works in any tool, and removes the most common failure in review threads: mistaking a suggestion for a demand.
What should I do when a review comment thread deadlocks?
Leave the thread. After roughly three rounds of back and forth, written debate stops converging and starts hardening positions. Take it to a call or a whiteboard, decide together, then return and record the outcome in one final comment so the resolution is visible to future readers. A sentence like "discussed offline: keeping the queue, adding a lag metric" preserves the context.
