Code-review disagreement becomes difficult when the author cannot tell whether a comment is a required change, a question, or a personal preference.
"This is wrong. Please redo it."
Even when the reviewer has found a real defect, that wording hides the evidence and makes the comment sound like a verdict on the author.
A useful review comment follows four steps:
Classify → evidence → consequence → request
Quick check
Test what you just read.
Ready to go beyond the quiz on "Caveat"?
Take the full learning path: hear it in real workplace contexts, watch short explanations, learn its nuances and when to use it, then practice using it yourself.
Start learning for free →Now see if you can use it naturally yourself.
Try it yourself
You know how to use "Caveat," too.
Keep going with the full learning path — more workplace contexts, related expressions, and continued practice.
Continue with "Caveat" →There's more to "Caveat" than it seems.
You've got part of it, but the full learning path goes deeper into its nuances, workplace contexts, and when it sounds natural — then gives you practice using it yourself.
Learn "Caveat" in depth →1. Classify the comment
Tell the author how the comment affects approval.
- Blocking: the reviewer believes the change should not merge yet.
- Non-blocking: the suggestion may improve the change but does not prevent approval.
- Question: the reviewer needs context before deciding.
- Nit: a small style or consistency point, normally non-blocking.
Labels vary across teams and review tools. Follow the team's convention—or define the labels before relying on them.
Examples:
"Blocking: this path can write the same payment twice when the client retries."
"Non-blocking suggestion: could we move this mapping into the shared formatter?"
"Question: is there a reason we keep the connection open across both calls?"
Do not label a material correctness concern as a nit merely to sound polite. Clear severity is usually more useful and respectful than soft language that conceals what approval requires.
2. Point to evidence or a violated requirement
Compare these comments:
"I don't like this approach."
"This retries the write after a timeout, but the operation is not idempotent. The integration test reproduces a duplicate record."
The second gives the author something they can inspect. Evidence may be a failing test, documented requirement, benchmark, security property, or reproducible behavior.
If the evidence is incomplete, use calibrated language:
"One caveat: I may be missing a constraint from the worker design. Could this branch process the event twice after a retry?"
Here, caveat introduces a limitation or condition that matters. It does not automatically make the comment non-blocking.
Want to actually use "Caveat" naturally at work?
Understanding it is one thing. Practice its nuances, see how it works in real workplace situations, and use it yourself with feedback.
Start the "Caveat" learning path →3. Explain the consequence
The author needs to know why the point matters.
"If the second request succeeds after the first response times out, the customer could be charged twice."
This is stronger than calling the implementation bad or unsafe without defining the failure. Keep the consequence proportional to the evidence. A possible duplicate request is not automatically a production incident.
Useful language:
- "The concern is that..."
- "In the retry case, this could..."
- "This makes the behavior dependent on..."
- "The trade-off is simpler code now versus..."
4. Make an actionable request
Finish with the change, evidence, or discussion needed next.
"Could we make the write idempotent and add a retry test before merging?"
"Can you add a comment explaining why this connection must remain open?"
"If you have benchmark data for this choice, could you link it here?"
An actionable request does not mean dictating an implementation when several solutions would work. State the property that must hold and let the author propose the design where appropriate.
Disagree with the decision, not the person
Personal:
"You misunderstood the lifecycle."
Technical:
"This assumes the worker remains alive after acknowledgment, but the runtime may terminate it immediately."
The technical version identifies the assumption under review. It also leaves room for the reviewer to be missing context.
Avoid automatic praise such as "great work, but" when the compliment is not genuine. Professional tone comes from specificity, proportionality, and respect—not from decorating every concern.
A realistic review exchange
Reviewer: Blocking: the retry path can submit the same request twice because the write has no idempotency key. The integration test reproduces it after a timeout. Could we make the operation idempotent and add that case before merging?
Author: I thought the gateway rejected duplicate payloads. Does that remove the concern?
Reviewer: That may be the context I was missing. Could you link the gateway guarantee? If it covers timeout retries, I can resolve the blocking comment and suggest documenting the dependency instead.
The reviewer is direct about the initial severity and willing to revise the judgment when new evidence appears.
Common mistakes
Turning preference into a requirement
"Use a switch statement."
If both forms meet the requirement, label the preference:
"Non-blocking: I find a switch easier to scan here, but the current version is correct."
Using “just” to make work sound trivial
"Just rewrite this using the repository pattern."
Just does not reduce the effort. Ask for the property you need and explain why.
Asking a fake question
"Don't you think this is too brittle?"
That is a criticism disguised as a question. Be direct:
"I think this is brittle because adding a new status requires changes in three separate maps. Could we keep the mapping in one place?"
Quick scenario challenge
Which comment gives the author the clearest path?
A. "This logic is confusing and needs work."
B. "Why would you do it this way?"
C. "Blocking: this loop has no upper bound when the cursor repeats. That could keep the worker running until timeout. Could we stop on a repeated cursor and add a test for it?"
Answer: C. It classifies the comment, identifies the evidence, explains the consequence, and requests a verifiable change.
Return to English for Software Engineers for more language for code reviews, architecture discussions, and stakeholder explanations.
Related guides
Try it
Lyra Practice helps advanced non-native English professionals learn the nuance of high-value workplace expressions and practice using them in realistic scenarios, so their English sounds natural, precise, and senior at work. Try Lyra Practice.