The best engineering teams I’ve seen treat code review as collaboration, not judgment. The worst teams treat it like a courtroom.
If code review feels painful in your team, it’s usually not because the code is bad. It’s because the culture is.
How to Write a Review Comment
- Be specific. “This is wrong” helps no one. “This fails when input is empty” is actionable.
- Separate style from correctness. Prefer automated formatters so humans don’t argue about commas.
- Explain the why. Especially for junior developers.
Examples
Bad: “This is messy. Fix it.”
Better: “Could we extract this logic into a helper? It will reduce duplication and make it easier to test.”
Best: “Could we extract this logic into formatPrice()? We already do similar formatting in checkout. This also makes it easier to unit test edge cases like null values.”
How to Receive Feedback
- Assume positive intent
- Ask clarifying questions instead of defending
- Don’t “win” the review; ship the best code
Practical Rules That Help
- Small PRs easier to review and less emotional
- Use “nit:” for low-priority feedback
- Use “suggestion:” for optional improvements
- Use “blocking:” only for real issues (bugs, security, correctness)
- Thank reviewers. They’re investing time in you.
Review Checklist
- Does this change have tests where it should?
- Are error cases handled?
- Does it introduce security issues?
- Will a new developer understand it in 6 months?
- Is the naming clear?
Code review isn’t about being right. It’s about building a shared understanding of the codebase. When you get that, everything else gets easier.