Writing Effective Review Comments
What you'll learn: How to write code review comments that clearly communicate problems, explain reasoning, and guide your teammates toward better solutions without causing friction.
The Core Idea
Effective review comments are like GPS directions for improvement—they tell someone where they need to go, why the current route won't work, and ideally offer a better path. Poor comments say "this is wrong" and leave the author confused or defensive. Great comments explain the reasoning, distinguish must-fix issues from suggestions, and foster learning.
The Three Elements of Quality Feedback
Explain the "Why"
Don't just say what's wrong—explain why it matters. Instead of "Don't use var here," write "Using let here prevents accidental reassignment and makes the scope clearer, which helps avoid bugs when this function grows."
Suggest Alternatives
When possible, show a path forward. "Consider extracting this validation logic into a helper function so it's reusable and testable" is more helpful than "This is messy."
Mark Requirements vs Preferences
Signal what's blocking vs nice-to-have. Use markers like:
- "Required:" for bugs, security issues, or violations of team standards
- "Nit:" or "Optional:" for style preferences or minor improvements
Think Like a Teacher, Not a Judge
Imagine reviewing a colleague's navigation algorithm. Instead of "This will fail," try: "This approach assumes the graph is acyclic. If we encounter a cycle, the function won't terminate. Could we add a visited set to handle that case?"
You're collaborating toward a shared goal, not grading a test.
Key Takeaway: Effective review comments explain why changes matter, offer actionable alternatives, and clearly distinguish between requirements and preferences—building both better code and better engineers.