Writing Code Review Comments People Actually Want to Read

Code review is a conversation between people who have to keep working together. The same technical point can land as helpful or hostile depending on how it is written.

Label the weight of each comment

Prefix comments so the author knows what is blocking: - nit: style or naming, take it or leave it. - suggestion: a better approach, but the current one works. - question: you do not understand something yet. - blocking: a bug, security issue, or broken contract that must change before merge.

This alone removes most review friction, because authors stop treating every comment as a demand.

Ask, then explain

"Why did you choose a list here?" sounds like a test. "Could a set work here? Lookups in this loop look O(n), which might hurt with large inputs" gives the reason and invites a reply.

Comment on the code, not the coder

Write "this function does three things" rather than "you made this too complicated." Use "we" for team conventions.

Be specific and offer a path

"This is confusing" is not actionable. Point to the line, say what confused you, and if you can, suggest a concrete alternative or a small code snippet.

Praise real things

A short "nice, this test covers the edge case I was worried about" is useful signal, not fluff. It tells the author what to keep doing.

Keep reviews small

Ask for pull requests under roughly 400 changed lines. Beyond that, reviewers skim and real problems slip through.

In interviews

"How do you give feedback in code reviews?" is a common behavioral question for engineers. A good answer mentions labeling severity, explaining the why, and keeping it about the code. To rehearse answers like this, I work on Linkjob.ai.