Fluent Start speaking

Workplace situation · Feedback and praise

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 (you are Senior Developer)

Goal: Get the code fixed and leave the author more confident, not less.

Step by step

  1. Comment on code. Talk about the code, never the coder: 'this function', not 'you'.
  2. Explain why. Give the reason or the risk, briefly.
  3. Suggest, don't command. Offer a fix as a question or a suggestion.
  4. Label weight. Mark comments as blocking, suggestion or nit.
  5. 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.

Rehearse this side out loud

Disagreeing as author (you are Developer)

Goal: Disagree with a review comment using reasons, and reach a decision without ego.

Step by step

  1. Assume good intent. The reviewer is protecting the codebase, not attacking you.
  2. Acknowledge the concern. Show you understood the point before disagreeing.
  3. Give your reason. Use data, constraints or trade-offs, not feelings.
  4. 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.

Rehearse this side out loud

Practice it out loud

Reading is half of it. Fluent listens to you say it and scores your clarity, free, in your browser.

Practice both sides

Related situations