Give Feedback That Lands
Feedback aimed at a person ("you are careless") is unactionable and triggers defence. Feedback pinned to a line, a behaviour, and its effect gives the learner one thing they can actually change.
Procedure
- Anchor to a concrete line: quote it with a path and range, e.g.
api/handler.py:42-47. - Use situation-behaviour-impact, in order: "When the request 404s (S), the handler returns 200 with an empty body (B), so the client retries forever (I)."
- Give one behaviour per pass. Two or more competing fixes dilute to none.
- Separate blocking from non-blocking explicitly: prefix nits with
nit:and label the restblocking:. - Describe the effect on the reader or the system, never the author's competence.
- Offer the smallest next action, or a question: "Would a 404 here be truer?" beats "this is wrong".
- For a repeated mistake, show the pattern across two diffs rather than re-litigating one instance.
- Close by naming what they did well specifically, so the contrast is instructive.
- If the fix is faster to show than to explain, show it once, then ask them to apply it elsewhere.
- Ask the author to restate the impact in their own words; if they cannot, the feedback did not land.
- Ask before asserting: 'what does the client do if this 200s on a 404?' often finds the bug with the author.
- Batch cosmetic nits into one comment so they do not crowd the one behavioural point.
- For a first-time author, open with the biggest win before the blocking item.
- Number your comments so the author can reply to 'comment 3' without pasting.
- State the trade-off when a change costs something, so the author can weigh it.
- Keep praise and correction in separate comments so neither dilutes the other.
Pitfalls
- Praising the person in general ("great coder") so the specific behaviour never lands.
- Burying a blocking bug inside five cosmetic nits, so the reader cannot rank the work.
- Framing impact as a feeling ("this frustrates me") instead of an observable effect.
- Rewriting the whole function in the comment, which teaches dependence on the reviewer.
- Delivering the same correction a third time without changing the form of the message.
- Sending feedback weeks after the diff, when the context has gone cold.
- Combining a correctness bug and a style opinion in the same comment.
- Using 'we' to mean 'you', so the author cannot tell what to change.
- Leaving the request open-ended with no smallest next step.
- Comments numbered nowhere, so a reply thread becomes a guessing game.
- Presenting a trade-off as a fault.
- Mixing praise into a blocking comment so the correction reads as softened.
Verification
git diff review-branch | grep -nE '^[+-]' | head
# passes when every comment you posted cites a file:line and states a consequence, none names a trait
Report to the user: the diff line each comment anchors to and the observable effect claimed in it.