Part 2 · 2 chapters · ~12 min

Writing Feedback People Act On

Labelling severity (blocking, should, nit, question, praise), conventional comments, giving the reason and a path, suggested changes, tone in text, when to move to a call, and avoiding the patterns that make review painful.

5

Six kinds of comment

code
conventional comments format:  <label> [decorations]: <subject>
issue (blocking): this retry generates a new idempotency key each attempt, so a timeout can double-post.
suggestion (non-blocking): extract computeFee() into fees.ts so it can be unit tested.
nitpick: `d` → `delta`.
question: is 30 s intentional here? other rail calls use 5 s.
praise: the transition table is very clear.
COMMENTS PEOPLE ACT ON
label the weight, give the reason, offer a path
blocking"This can double-post on retry:the key is generated per attempt.Generate it once per intent?"should"Consider moving the feecalculation into the domain moduleso the controller stays thin."nit"nit: rename `d` to `delta`."Optional; never blocks.question"Why a 30 s timeout here? Iexpected 5 s like the other railcalls." Genuinely asking.praise"Nice: the state table makes theillegal transitions obvious."Specific praise teaches too.toneComment on the code, not theperson; "we" and questions overcommands.
swipe the figure sideways, or tap expand for full screen
1/6
blocking
Say clearly what must change and why it matters (a bug, a security issue, data loss), and suggest a path. Unlabelled comments all look blocking to the author.
must change: say why, suggest howlabel it, or everything looks blocking
6

Patterns that make review painful

anti-patternbetter
a new round of comments each time the old ones are fixeddo a full pass the first time
"why didn't you just…""what do you think about…? It would avoid X"
rewriting the PR in commentspair, or open a follow-up PR yourself
approving without readingsay "LGTM for the migration only; did not review the UI"
sitting on a review for daysrespond within a working day, even if only to say when you will