Code reviews are a cornerstone of high quality software development. But not all code reviews are equal. Some are dreaded, others are welcomed. The difference usually lies not in the complexity of the code, but in the way the review is conducted.
This post dives into what makes a great code review, in my opinion, and how to phrase comments in a way that’s helpful, respectful, and effective.
What Makes a Good Code Review?
Understand the Context
Don’t jump straight into the diff. Start by:
- Reading the PR title and description.
- Understanding the goal of the changes.
- Asking questions if the context isn’t clear.
You can’t review what you don’t understand.
Focus on the Code, Not the Coder
Make your feedback about the code, not the person who wrote it.
- ❌ Bad: “You forgot to handle nulls again.”
- ✅ Good: “This might throw if user is null. Could we add a guard clause?”
Prioritise Comments by Importance
Not every comment is a blocker. Use tiers to signal intent:
- Blocking: Needs fixing before merging (e.g., security bug).
- Suggestion: Could improve performance/readability but not critical.
- Nitpick: Pure style or personal preference.
Use labels like nit, suggestion, or optional.
Be Specific and Provide Reasoning
If you want something changed, explain why.
- ❌ Vague: “Rename this.”
- ✅ Clear: “Consider renaming to isActive, it better reflects the boolean nature of this value.”
Ask Questions Instead of Demanding
If you’re unsure, phrase it as a question.
- “Would it make sense to extract this into a utility function?”
- “Is there a reason we’re using a for-loop here instead of Array.map()?”
This opens a dialogue instead of shutting one down.
Acknowledge Good Work
Positive feedback is just as valuable as critical feedback.
- “Nice clean-up here, removing that legacy logic really simplifies things.”
- “Great edge case handling!”
A small compliment can make someone’s day.
Don’t Over-Review
Avoid commenting on every little thing in a large PR. Focus on areas of:
- Complexity
- Risk
- Learning opportunities
And if it’s too big to review in one go, say so.
How to Phrase Code Review Comments
Here’s a cheat sheet to phrase your feedback:
Suggestions
- “Consider using const instead of let here.”
- “What do you think about moving this logic to a helper?”
Clarifications
- “Could you walk me through the reason for this approach?”
- “Is there a case where this might break?”
Blockers
- “This will break when foo is null. Can we add a check here?”
- “This introduces a security vulnerability that needs fixing before merging.”
Nitpicks
- “nit: Tiny style thing, extra space here.”
- “Not a blocker, but aligning this with our usual naming helps consistency.”
Praise
- “Great use of destructuring, keeps things clean!”
- “Love how this is modularised.”
Final Thoughts
A good code review:
- Helps the team grow
- Produces better code
- Builds trust and collaboration
Remember, the goal is not to be right, but to get it right together.
Be kind, be clear, and make every review a chance to learn.