How to give code review feedback that developers actually use

Comments That Change Behavior

A code review comment is a communication, not a correction. Its goal is to improve the code while preserving the author's ownership and motivation to contribute. Most review feedback fails because it says what to change without explaining why.

Comment Types and Language

// Blocker — must be fixed before merge:
// "[Blocker] This doesn't validate that userId is a valid ObjectId before
// the database query — invalid inputs will throw a Mongoose CastError
// that leaks internal error details to the client."

// Suggestion — should consider:
// "[Suggestion] Consider extracting the retry logic into a
// withRetry(fn, attempts) utility — we have similar logic in 3 other places."

// Nit — optional, low priority:
// "[Nit] Variable name 'd' could be 'durationMs' for clarity,
// but not blocking."

Questions Are More Effective Than Demands

// Demand (defensive reaction likely):
// "This is wrong. Use === not =="

// Question (opens a conversation):
// "Is there a reason we're using == here rather than ===?
// I'd expect strict equality to be safer."

// Explain the why — make it a teaching moment:
// "This mutation of the options default causes subtle bugs when the function
// is called multiple times — each call sees the decremented retries value.
// Spread the defaults instead: { ...DEFAULT_OPTIONS, ...options }"

Always acknowledge what's done well. A review with only problems suggests the reviewer didn't see the good parts — and makes authors reluctant to submit.