How to Write Code Review Comments Without Sounding Rude

You type a perfectly ordinary code review comment—"Why did you do it this way?"—and immediately wonder whether it sounds curious, accusatory, or like you are preparing a disciplinary hearing.

Text removes facial expression, timing, and tone. A terse comment can look annoyed even when you wrote it between meetings with no emotion at all. The solution is not to wrap every concern in five layers of praise. It is to make your intent, evidence, and requested action unmistakable.

Good review language protects two things at once: the quality of the code and the working relationship. Here is a repeatable way to do both.

Review the Code, Not the Coder

Comments become personal when they make claims about the author: "You forgot error handling," "You misunderstood the requirement," or "You made this too complicated." Even if the observation is correct, the grammar puts the person on trial.

Move the subject of the sentence to the code or behavior: "This path does not handle a failed request yet," "This behavior differs from the acceptance criteria," or "This abstraction adds two layers before the value is used."

This is not empty politeness. It makes the discussion easier to verify. People can inspect whether a path handles an error; they cannot productively debate whether they are careless.

The same principle anchors our broader guide to giving and taking feedback without making it personal: keep the feedback attached to observable work and a useful next step.

Label the Kind of Comment You Are Making

The author should not have to guess whether your comment blocks the merge. A small prefix creates a shared protocol: Blocking, Suggestion, Question, Nit, or Praise.

Use Blocking for a change required before merge. Use Suggestion for a genuine improvement the author can decline. Use Question when you need context. Use Nit for a tiny, optional preference—sparingly, especially when a formatter or lint rule should settle it instead. Use Praise to point out a choice worth repeating.

Labels only work when you honor them. Do not write "Nit" and then withhold approval over it. Do not label a correctness bug "Maybe" to sound kind. Clarity is part of kindness because it lets the author decide what to do next.

Use Context + Impact + Next Step

A strong comment contains up to three pieces. Context: what behavior you observe and under what condition. Impact: why it matters. Next step: the change, question, or option that moves the review forward.

Example: "When the token expires, user can be null here. Accessing user.id would then throw and return a 500. Blocking: could we handle the expired-session case before this line?"

Not every comment needs a paragraph. "Nit: could we use the existing formatDate helper for consistency?" is complete because the stakes are low and the request is obvious. Add context in proportion to the cost and controversy of the requested change.

When you have a proposed edit that is small and unambiguous, offer it as a suggestion. When multiple approaches are reasonable, describe the constraint and invite the author into the choice.

Replace These Rude-Sounding Comments

Instead of: "Why would you do this?" Try: "Question: what constraint led to this approach? I expected the shared client here and may be missing context."

Instead of: "This is wrong." Try: "This returns the cached permission after a role changes, so the user may keep access until expiry. Blocking: we need to invalidate this key on role updates."

Instead of: "Just use a map." Try: "Suggestion: a map could reduce this to one lookup per item. Would that also preserve the ordering requirement?"

Instead of: "Obviously this needs a test." Try: "Could we add a test for the empty response? That is the branch most likely to regress here."

Instead of: "This is overengineered." Try: "I see three abstractions for one current implementation. What future variation are we protecting? If none is planned, I suggest keeping this in one module for now."

Instead of: "Rename this." Try: "Suggestion: activeSubscription would distinguish this from the full subscription history."

Instead of: "No." Try: "Blocking: this bypasses the authorization check on the bulk path. Please route it through canEditAccount, as the single-item path does."

Be Direct About Bugs, Security, and Data Risk

Respectful does not mean vague. If a change can corrupt data, expose information, or break a documented requirement, say that plainly and mark it blocking.

Try: "Blocking: two requests can update this balance concurrently, so the final value can be wrong. We need the update to be atomic. One option is the existing transaction helper in the payments module."

Notice the tone: factual, specific, and calm. There is no apology for raising the issue, and no speculation about how the author missed it. The comment gives them a reproducible concern and a possible route forward.

If you are not certain, show your uncertainty: "Potential blocker: could these jobs process the same account at once? If yes, I think this update needs a lock; if the queue guarantees uniqueness, a comment documenting that guarantee would resolve my concern."

Disagree About Design Without Turning It into Taste

Design comments become tense when preferences masquerade as universal rules. Anchor the discussion to an agreed constraint: maintenance cost, latency, compatibility, team convention, or the scope of the current change.

Try: "I prefer keeping this logic in the domain service because both the API and worker need it. Duplicating it here could let the behaviors drift. Is there a reason the worker cannot depend on that service?"

If the choice is reversible and both options satisfy the requirements, consider approving with a non-blocking suggestion. Code review is a quality gate, not an opportunity to make every line look as if you wrote it.

When the disagreement affects several teams or needs a real trade-off decision, stop debating via fragments. Use the approach from speaking up at work: lead with the recommendation, name the constraint, and invite the missing perspective.

Praise Specific Decisions, Not Just the Whole PR

Review comments should not exist only where something is wrong. Specific praise teaches the author and future readers what good looks like.

"Nice work" is warm but not very informative. Try: "Praise: separating parsing from validation makes the failure cases much easier to test," or "This migration fallback is thoughtful—it lets old clients keep working during rollout."

Do not use praise as a sandwich around criticism. People recognize forced compliments. Leave genuine positive comments where you see a strong decision, and make critical comments clear enough to stand on their own.

Know When to Leave the Review Thread

Move to a call or pairing session when a thread has repeated the same positions twice, when the decision depends on unstated context, or when the tone is becoming the topic. Write: "I think we're optimizing for different constraints. Can we take ten minutes to compare them, then post the decision here?"

Afterward, leave a short record: what was decided, why, and any follow-up. The conversation creates bandwidth; the written summary preserves the engineering context.

If a comment lands badly, repair it without defending your intention: "Reading that back, my wording was sharper than I intended. The concern is the retry behavior, not your decision-making. Here's the case I'm worried about." That sentence costs little and can reset the entire interaction.

Your Pre-Submit Review

Before posting, check four things: Is the severity clear? Is the observation verifiable? Did I explain the impact when it is not obvious? Does the author know what response or change would resolve the comment?

Then delete any judgment about the person and any word that makes the task sound easier than it is. You will end up with comments that are shorter, firmer, and easier to act on—not artificially cheerful, simply professional.

For practice with tone outside a live pull request, use the Communication Trainer. You can also browse more work communication guides for feedback, meetings, and speaking up.