Code review comments
A review comment interrupts a person mid-flow. It lands when the author can
tell in one read how much it matters and what to do next. Comments that bury
a blocker among nitpicks, or dress a firm objection as a coy question, waste
both people's time and stall the merge.
Method
- Label severity up front. Prefix each comment:
blocking:, nit:,
question:, praise:, following a convention like Conventional
Comments. The author triages a 30-comment review in seconds when severity
is explicit, and guesses wrong when it is not.
- Separate directives from questions honestly. If a change must happen,
say so: "blocking: this leaks the DB connection on the error path." If you
are genuinely unsure, ask a real question and mean it. A rhetorical "did
you consider...?" that actually demands a change reads as passive.
- Say why, and show how where it is cheap. "This N+1 fires one query
per row; batch it with a single
WHERE id IN (...)" beats "inefficient."
The reason lets the author generalize; a GitHub suggestion block lets them
accept the fix in one click.
- Comment on the code, never the coder. "This function does three
things," not "you always over-scope." Keep it to the diff in front of you;
opinions about someone's habits belong in a private conversation.
- Cap the nits, or automate them. More than a few
nit: on style means
a linter rule is missing. Push spacing, import order, and naming casing
into prettier, eslint, or ruff so review spends on logic.
- Reach a verdict. Do not leave a review in limbo with ten comments and
no decision. If nothing blocks, approve and trust the author with the
nits. Reserve "request changes" for real blockers.
Litmus tests
- Can the author sort your comments into "must fix now" and "later" without
asking you?
- Does each blocking comment state a concrete failure, not a preference?
- Would you say the comment out loud, in these words, to the author's face?
Boundaries
Team norms on approval gates and required reviewers override personal style:
follow the repo's CODEOWNERS and review policy. A design disagreement too
large for a line comment belongs in a call or a design doc, not a buried
thread.
1---2name: code-review-comments3description: Write review comments that land by labeling severity and separating genuine questions from directives. Use when leaving comments on a pull request or coaching someone on how theirs read.4---56# Code review comments78A review comment interrupts a person mid-flow. It lands when the author can9tell in one read how much it matters and what to do next. Comments that bury10a blocker among nitpicks, or dress a firm objection as a coy question, waste11both people's time and stall the merge.1213## Method14151. **Label severity up front.** Prefix each comment: `blocking:`, `nit:`,16 `question:`, `praise:`, following a convention like Conventional17 Comments. The author triages a 30-comment review in seconds when severity18 is explicit, and guesses wrong when it is not.192. **Separate directives from questions honestly.** If a change must happen,20 say so: "blocking: this leaks the DB connection on the error path." If you21 are genuinely unsure, ask a real question and mean it. A rhetorical "did22 you consider...?" that actually demands a change reads as passive.233. **Say why, and show how where it is cheap.** "This N+1 fires one query24 per row; batch it with a single `WHERE id IN (...)`" beats "inefficient."25 The reason lets the author generalize; a GitHub suggestion block lets them26 accept the fix in one click.274. **Comment on the code, never the coder.** "This function does three28 things," not "you always over-scope." Keep it to the diff in front of you;29 opinions about someone's habits belong in a private conversation.305. **Cap the nits, or automate them.** More than a few `nit:` on style means31 a linter rule is missing. Push spacing, import order, and naming casing32 into `prettier`, `eslint`, or `ruff` so review spends on logic.336. **Reach a verdict.** Do not leave a review in limbo with ten comments and34 no decision. If nothing blocks, approve and trust the author with the35 nits. Reserve "request changes" for real blockers.3637## Litmus tests3839- Can the author sort your comments into "must fix now" and "later" without40 asking you?41- Does each blocking comment state a concrete failure, not a preference?42- Would you say the comment out loud, in these words, to the author's face?4344## Boundaries4546Team norms on approval gates and required reviewers override personal style:47follow the repo's `CODEOWNERS` and review policy. A design disagreement too48large for a line comment belongs in a call or a design doc, not a buried49thread.
Amey-Thakur