Code Review Comments Developers Can Use
Write code review feedback that is specific, respectful, and easy to act on.
Describe the effect
A useful review comment explains what can happen: a duplicated query, a missing authorization check, an ambiguous return value, or a failure under a specific input.
Avoid labels such as bad or messy. Point to the behavior and its consequence so the author can evaluate the concern without decoding the reviewer’s tone.
Make the next step clear
When the fix is straightforward, suggest the smallest concrete change. When several approaches are valid, ask a focused question rather than prescribing a complete rewrite.
Separate blocking correctness issues from optional preferences. That distinction keeps pull requests moving and prevents style discussions from hiding real risks.
Share enough surrounding code
A screenshot can help explain a review lesson outside the pull request, but include enough lines to show the cause and result. Highlighting one line without its branch or caller often creates the wrong lesson.
Remove project names and sensitive values before sharing. The teaching point should survive without exposing a private codebase.