How to Disagree in a Code Review Without Sounding Aggressive

Author: Ksenia Izotova
Last updated: September 2026

Name the concern in the code, explain the consequence, and make clear whether you need a change, want to discuss an option or are asking for information. Refer to observable behaviour, tests or an agreed standard. Give the author room to explain context you may have missed. A direct comment can be respectful when its reasoning is visible. Adding several apologies or “maybe” to every sentence can make the requested action harder to understand.

“Why did you do it like this?” is a familiar review comment. The reviewer may mean, “I'd like to understand the design.” The author may hear, “This was a poor decision.”

A useful alternative is:
“I expected this check to happen before the write. Is there a constraint that requires the current order?”

The question now identifies the point of uncertainty. The author has something specific to answer.

Google’s engineering guidance recommends respectful comments about the code, explanations of reasoning and clear labels for required versus optional changes. Source: Google Engineering Practices, Review Comments

Apply that distinction in the sentence itself. “You forgot validation” focuses attention on the author’s mistake. “This path accepts an empty value; please add validation before saving” focuses on behaviour and action.

You do not have to avoid the word “you” in every exchange. “Could you add a test for this case?” is a normal request. The issue is assigning motives, competence or blame when the review needs technical reasoning.

The function now handles both validation and persistence, and its responsibilities are difficult to follow. “This makes no sense” gives the author a judgement, but no explanation of what should change.

Try: “I’m having trouble following where validation ends and saving begins. Could we separate those steps, or clarify why they need to stay together?”

This leaves space for an explanation. If separation is genuinely required by an agreed standard, cite that standard and make the request explicit.

Suppose you suspect that a loop makes a separate network request for each record. “Obviously” suggests that the author should have known better, while “won't scale” leaves the threshold unspecified.

“This appears to send one request per record. Have we checked it with the larger imports we support? I’m concerned about request limits.”

If you have measured the problem, include the result. If you have not, keep it framed as a concern to verify.

The error-path test is required before approval under your team's review rules. With both “maybe” and “perhaps,” the author may reasonably read the comment as optional.

Be direct: “Required before approval: please add a test for the timeout path. We need to verify the error response this change introduces.”

Directness helps here. The label and reason explain why the change is needed.

You have a possible improvement to a repeated lookup, but no evidence that the existing approach causes a problem. “Use a map” sounds mandatory, and the reason for the suggestion is hidden.

“Optional: a map might make the repeated lookup easier to read. I’m comfortable with the current version if you prefer to keep this change small.”

Only call it optional if approval truly does not depend on it.

Agree labels within your team. The exact words matter less than shared understanding.

“Nit” is common in some teams but unfamiliar in others. Explain it if you use it, and state whether it blocks approval. Labels supplement your repository’s review process; they do not replace it.

An author needs equally clear language. “No, that won't work” usually starts another round because it does not explain the constraint.

Consider this exchange:

Reviewer: “Could we use the existing helper here?”

Author: “I considered it. The helper assumes a signed-in user, while this endpoint also serves guest requests. I’ve kept this check local for now. Would a shared helper that handles both paths be worth a separate change?”

The author explains the decision without implying that the reviewer should already know the constraint.

If the reviewer is right, close the loop clearly:
“Agreed. I missed the guest path. I’ve added the check and a regression test.”

If you misunderstood their comment:
“I read your comment as a request to change the public API. I now see you meant the internal helper. I’ll update that part.”

This is more useful than continuing to defend an interpretation the reviewer did not intend.

Written reviews become difficult when several assumptions are being disputed at once. Suggest a short conversation with a defined question:

“We seem to be making different assumptions about retry behaviour. Could we spend ten minutes checking that together? I’ll add the agreed decision here afterwards.”

If agreement still is not possible, use the team’s established decision owner or escalation process. Do not silently merge past a blocking review.

Record the decision where future readers can find it. A conversation can resolve tension, but the relevant reasoning may still belong in the code, documentation or change discussion.

If the concern is difficult to phrase, draft the technical reason first. Add a respectful request around that reason. Replacing every direct verb with an apology usually does less to help.

UnifyHub’s English for software engineers programme covers code reviews and technical discussions. Teams can book an assessment to identify where language is getting in the way. For spoken disagreements in team discussions, see how to lead a retrospective in English.

Take one non-confidential review comment and rewrite it as a required change, a suggestion and a genuine question. Then answer each version. This is a quick way to see how a small wording change affects the action the author expects to take.

Author: Ksenia Izotova
Last updated: September 2026