I review a lot of code. And I see a lot of comments that make people defensive.
The person writing them doesn't mean to be rude. They're just being direct. But in English - especially written English - directness can feel harsh.
Here's the problem: you can't hear tone in text. There's no friendly smile. No "I'm just trying to help" body language. Just words on a screen.
Let's fix that.
The Difference One Word Makes
Look at these two comments:
❌ "This is wrong."
✅ "I think this might cause issues because..."
Same message. Completely different feeling.
The first one sounds like a judgment. The second sounds like a conversation.
5 Patterns That Sound Harsh (And What to Say Instead)
1. "You should..."
This sounds like a command. Like you're the boss.
❌ "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...?"
This sounds like an interrogation. Like you're suspicious.
❌ "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."
This sounds like you're calling someone 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 things sound trivial. Like the person should have known better.
❌ "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. Shows you know it takes effort.
5. "This is inefficient / bad / wrong."
Labels feel personal. Even when you're talking about 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: You acknowledge the code works. Then you suggest improvement.
The Magic Phrases
Keep these in your back pocket:
| Instead of... | Try... |
|---|
| "You need to..." | "Could we..." |
| "This is wrong" | "I think there might be an issue with..." |
| "Why didn't you..." | "I'm curious why..." |
| "Obviously..." | (Just delete this word) |
| "Just..." | (Delete this too) |
| "You forgot to..." | "It looks like we might need..." |
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, being direct is respectful. It shows honesty.
In English professional culture, being indirect is often more respectful. It shows you value the other person's judgment.
Neither is right or wrong. But if you're writing in English to an international team, a little softness goes a long way.
Quick Practice
Rewrite these in your head (or in the comments):
- "You should rename this variable."
- "This function is too long."
- "Why are you using callbacks instead of async/await?"
Vocabulary from This Article
| Word | What it means | Example |
|---|
| harsh | too strong, unkind | "The feedback felt harsh." |
| defensive | protecting yourself from criticism | "He got defensive when I mentioned the bug." |
| dismissive | treating something as unimportant | "'Just fix it' sounds dismissive." |
| humble | not thinking you're better than others | "Starting with 'I might be wrong' is humble." |
| cushioning | making something softer or less direct | "Facts don't need cushioning." |
Your Turn
What's the worst code review comment you've ever received?
Or the best one - the one that taught you something without making you feel bad?
Drop it in the comments. Let's learn from each other.
I'm Jacques, an English teacher who works with developers. I help non-native speakers communicate with confidence in technical environments.