English for code reviews: comments and phrases that don't sound rude
How to write and say code review feedback in English without sounding harsh: softeners, questions instead of orders, labels for comments, and phrases for PR walkthroughs.
3 min read
Code review comments sound rude in English mostly because of directness, not vocabulary. "Change this to a map" is a normal sentence in many Central and Eastern European teams. To many native English speakers it reads as an order, and slightly annoyed. Add one softener or turn it into a question, and the same comment sounds collaborative.
This article covers written comments first, then the spoken part: walking someone through your pull request on a call.
Softeners: the smallest change with the biggest effect
| Direct (can sound harsh) | Softened |
|---|---|
| Change this to a map. | What do you think about using a map here? |
| This is wrong. | I think this might break when the list is empty. |
| Don't use any. | Could we type this more strictly? any hides errors. |
| Rename this variable. | Nit: maybe retryCount instead of n? |
| Why did you do it this way? | I'm curious about the reasoning here. Was it for speed? |
The softeners are small words: "I think", "maybe", "could we", "what do you think about". They are not a sign of weakness. They signal that the comment is about the code, not about the person. Linguists describe this as protecting the other person's "face" (Politeness theory, Wikipedia).
Label your comments
Much of the tension in reviews comes from not knowing how serious a comment is. Labels fix that. The Conventional Comments format suggests prefixes such as suggestion:, issue:, question:, nitpick: and praise:, plus a note on whether the comment blocks the merge (Conventional Comments).
nitpick (non-blocking): extra blank line here.
issue: this query runs inside the loop, so we'll hit the database once per item.
question: is this timeout the same as the one in the config?
Even without the full format, "Nit:" in front of a minor comment is widely understood and saves the author from wondering whether you are unhappy.
Phrases for written comments
Nice approach, this is much easier to read.Praise is part of a review. Say it when it's true. Not a blocker, but…Makes clear the PR can be merged anyway. Could you add a test for the empty case?Request phrased as a question. I might be missing something, but…Useful when you are not sure you're right. Happy to discuss on a call if that's easier.Moves long threads to a conversation.Receiving feedback
Good catch, fixed.The most common reply to a valid comment. I went with this because… but I'm open to changing it.Defending a decision without being defensive. Let's leave it for a follow-up PR.Agreeing, but not now.Walking someone through your PR on a call
Speaking about code is harder than writing about it, because you cannot edit. Use a simple structure: context, the main change, what to look at carefully.
Let me share my screen.Starts the walkthrough. The interesting part is here.Directs attention to what matters. I'm not sure about this bit, so feedback is welcome.Invites review where you need it.So, the context: the export was timing out for big accounts. The main change is in the export service: instead of loading everything at once, we now stream the rows in batches. The part I'd like you to look at carefully is the retry logic, because I'm not a hundred percent sure about the error cases.
Practise the spoken part
Written comments can be edited until they sound right. The walkthrough cannot, so practise it out loud. In FluentSession you can describe the tutor as "a senior reviewer who asks why you made each decision" and explain a recent pull request. If you also want to explain bugs more clearly, read How to explain a bug in English.