Code review comments
Review code without bruising people, and push back on a review without starting a war.
Case study: The one-word review
Rohit, a fresher in Pune, opened his first pull request at a product company. The senior reviewer left eleven comments. Most said only "Why?", "Wrong." or "No." Rohit spent the evening rewriting everything, including parts that were fine, and stopped raising PRs until the last day of the sprint. His lead, Farah, rewrote one comment as an example: "This loop calls the database once per user, so with 10,000 users it'll be slow. Could we fetch them in one query? Happy to pair on it." Same point, different result. Rohit fixed it in twenty minutes and asked her two more questions.
Takeaway: A review comment should explain the why and suggest a way forward. The code gets better and so does the person.
Some of us read terse comments as normal seniority, and others never push back on a senior's review out of respect. Global teams expect reviews to be kind and reasoned, and expect authors to disagree openly when they have a reason.
Reviewing kindly
Goal: Get the code fixed and leave the author more confident, not less.
Step by step
- Comment on code. Talk about the code, never the coder: 'this function', not 'you'.
- Explain why. Give the reason or the risk, briefly.
- Suggest, don't command. Offer a fix as a question or a suggestion.
- Label weight. Mark comments as blocking, suggestion or nit.
- Praise something real. Point out at least one thing done well.
Say this, not that
| This loop calls the database once per user. With ten thousand users it'll get slow. Could we fetch them in one query? | Wrong. Fix this. | The reason turns an order into a lesson. |
| Small nit, not blocking: I'd rename this variable to something like retry count. | Change this name. | Labeling severity stops juniors from treating every comment as a crisis. |
| What do you think about moving this into a helper function? | Why did you do it like this? | 'Why did you' sounds like an accusation. 'What do you think' invites a discussion. |
| Nice job on the test coverage here. That made this much easier to review. | ||
| There are a few comments, so happy to jump on a quick call if that's easier. |
Model conversation
- You
- Hey Rohit, I left some comments on your PR. Want to go through them quickly on a call?
- Rohit
- Yes please. I saw there are eleven. Is it very bad?
- You
- Not at all. Only two are blocking, the rest are small suggestions. And your tests are really thorough.
- Rohit
- Oh, that's a relief. What are the two big ones?
- You
- The main one is the user loop. It calls the database once per user, so at scale it'll be slow. Could we fetch everyone in one query?
- Rohit
- Makes sense. I didn't think about the volume. I can use a batch query.
- You
- Perfect. The other is a missing null check on the address. The rest you can take or leave.
- Rohit
- Got it. I'll push the fixes by this evening. Thanks for explaining.
Disagreeing as author
Goal: Disagree with a review comment using reasons, and reach a decision without ego.
Step by step
- Assume good intent. The reviewer is protecting the codebase, not attacking you.
- Acknowledge the concern. Show you understood the point before disagreeing.
- Give your reason. Use data, constraints or trade-offs, not feelings.
- Propose a resolution. Offer a compromise, a follow-up ticket or a quick call.
Say this, not that
| Thanks for the review. I see your point about readability. | But it's working, no? | 'It works' ignores the reviewer's actual concern. |
| I went with this approach because the caching cut response time by half in my benchmark. | I just prefer it this way. | Reasons and data move reviewers. Insistence doesn't. |
| Would you be open to keeping it for now and adding a ticket to refactor it next sprint? | ||
| I may be missing something. Could you help me understand the risk you're seeing? | Okay, okay, I will change. | Silently giving in teaches nothing, and you may be right. |
| This thread is getting long. Could we jump on a ten minute call? | Calls resolve in minutes what comments drag out for days. |
Model conversation
- Sanne
- I left a blocking comment. I'd prefer not to add a cache layer here. It adds complexity.
- You
- Thanks, Sanne. I agree it adds complexity. Can I share why I went with it?
- Sanne
- Sure, go ahead.
- You
- Without the cache, the pricing call takes eight hundred milliseconds. With it, it's under two hundred. The client has a three hundred millisecond target.
- Sanne
- Ah, I didn't know about the target. That changes things.
- You
- Would it help if I added tests for cache expiry and a short comment explaining the trade-off?
- Sanne
- Yes, that would address my concern. Let's do that.
- You
- Great. I'll push it this afternoon and tag you.
Practice it out loud
Reading is half of it. Fluent listens to you say it and scores your clarity, free, in your browser.