How to Write Code Review Comments That Don't Sound Rude

Source: Dev.to

The Difference One Word Makes

❌ “This is wrong.”
✅ “I think this might cause issues because …”

Both convey the same message, but the second feels conversational rather than judgmental.

5 Patterns That Sound Harsh (And What to Say Instead)

1. “You should …”

Sounds like a command.

• ❌ “You should use a constant here.”
• ✅ “What do you think about using a constant here?”
• ✅ “Have you considered using a constant here?”

Why it works: Questions invite discussion; commands shut it down.

2. “Why did you …?”

Sounds like an interrogation.

• ❌ “Why did you use a for loop here?”
• ✅ “I’m curious about the for loop—was there a specific reason you chose it over map?”
• ✅ “Just wondering—is there an advantage to the for‑loop approach here?”

Why it works: “I’m curious” shows genuine interest, not judgment.

3. “This doesn’t make sense.”

Implies the author is confused or stupid.

• ❌ “This logic doesn’t make sense.”
• ✅ “I’m having trouble following this logic—could you walk me through it?”
• ✅ “I might be missing something, but I’m not sure how this handles the edge case.”

Why it works: You take responsibility for not understanding; it’s humble.

4. “Just do X.”

“Just” makes the request sound trivial or dismissive.

• ❌ “Just add error handling.”
• ✅ “It would be great to add some error handling here.”
• ✅ “Could we add error handling for the null case?”

Why it works: Removes the dismissive tone and acknowledges effort.

5. “This is inefficient / bad / wrong.”

Labels feel personal, even when referring to code.

• ❌ “This approach is inefficient.”
• ✅ “I wonder if we could improve performance here by …”
• ✅ “This works, but I’m thinking we might hit performance issues at scale. What if we tried …?”

Why it works: Acknowledge that the code works, then suggest improvement.

The Magic Phrases

Keep these alternatives handy:

When to Be Direct

Not every comment needs softening. Be direct when:

• There’s a clear bug – “This will throw a null‑pointer exception on line 42.”
• There’s a security issue – “This exposes the API key. Let’s move it to environment variables.”
• It’s a simple fact – “This function is missing a return statement.”

Facts don’t need cushioning; opinions do.

Cultural Note

In some cultures, directness is a sign of respect and honesty. In English‑language professional settings, indirectness is often perceived as more respectful because it shows you value the other person’s judgment. Neither approach is inherently right or wrong, but when writing in English for an international team, a little softness can go a long way.

Quick Practice

Rewrite the following in a softer tone (or as you would in a comment):

• “You should rename this variable.”
• “This function is too long.”
• “Why are you using callbacks instead of async/await?”

Vocabulary from This Article

Your Turn

What’s the worst code‑review comment you’ve ever received?
Or the best one—the comment that taught you something without making you feel bad?

Share it in the comments so we can all learn from each other.