Aim feedback at the code and the goal, never the person. Be specific, explain why, separate must-fix issues from preferences, and ask questions where you are unsure. Mention what is good, give bigger feedback privately and in conversation, and let the team's agreed standards do the arguing for you.
What people tell me
I review other developers' code or work closely with them, and I often see things I think should be done differently. Some are real problems, some are just my preference. When I have pointed things out before, people have become defensive, or long comment threads turned into arguments. Now I sometimes approve things I am not happy with just to avoid tension. I want to give honest feedback without damaging relationships.
A composite of the messages behind this question, with personal details left out.
Key takeaways
- Comment on the code and its effect, never on the person who wrote it.
- Label comments: must fix, suggestion, or question. Most arguments come from preferences disguised as rules.
- Explain why. A reason can be discussed; a verdict can only be accepted or resisted.
- Move long threads to a quick call, and give bigger feedback about habits privately.
- Approving work you think is wrong to avoid tension is not kindness. It moves the cost later.
Why feedback turns into conflict
Most review conflict does not come from people being difficult. It comes from feedback that feels like a judgement of the person, that mixes serious problems with personal taste, or that gives verdicts without reasons. Fix those three things and most tension disappears.
Aim at the code, not the person
Small wording changes make a large difference:
| Instead of | Try |
|---|---|
| "You forgot to handle errors" | "This call can fail if the service is down. What should happen then?" |
| "This is wrong" | "I think this returns the wrong total when the cart is empty. Here is the case I tried." |
| "Why would you do it this way?" | "What led to this approach? I was expecting X and want to understand." |
| "This is messy" | "Could we split this function? It handles parsing and saving, which makes it hard to test." |
Questions and observations invite a conversation. Accusations invite defence.
Label what kind of comment it is
A lot of arguments happen because the author cannot tell whether a comment is a blocker or a preference. Make it explicit:
- Must fix: bugs, security issues, broken requirements, missing tests the team requires.
- Suggestion: a better approach you would like considered, but the author can decline.
- Nit: naming, formatting, small style points. Optional.
- Question: you do not understand something and want to.
When you are honest that something is just your preference, people relax, and they take your must-fix comments more seriously.
Always explain why
"Use a map here" is a verdict. "A map here makes the lookup constant time, and this runs for every row in the import" is a reason. Reasons can be discussed, agreed with or corrected. They also teach, which means you will see the problem less often.
If you cannot explain why, it may be a preference. Label it as one or let it go.
Mention what is good
Not as a trick to soften criticism, but because it is useful information. "Nice, the tests here make this really easy to follow" tells the author what to keep doing. Reviews that are only a list of problems feel like attacks, even when every point is fair.
Know when to leave the comment thread
Written comments lose tone. If a thread goes past two or three replies, suggest a quick call:
"I think we are talking past each other a little. Can we jump on a five-minute call?"
Most disagreements resolve in minutes when spoken, and you avoid a public back-and-forth that others can read.
Bigger feedback belongs in private
Review comments are for the code in front of you. If you notice a pattern, for example someone often skips tests or ships without checking edge cases, that is feedback about a habit. Give it one to one, calmly, with examples, and with an offer to help. Better still, if you are not their lead, suggest the team agree on a shared standard.
Let shared standards do the work
Many review arguments are about style and conventions. Move those out of individual judgement:
- Automate formatting and linting so nobody argues about spacing.
- Agree on a short list of team conventions and write them down.
- Refer to the agreement rather than your opinion: "Our guideline says we test public API changes."
This turns "I think" into "we agreed", which takes the personal element away.
Do not approve things you think are wrong
Approving a change you believe will cause problems, just to avoid tension, feels kind. It is not. The cost comes back later as a bug, a rewrite, or frustration when the issue surfaces and people ask why no one said anything. Honest, respectful feedback now is the kinder option.
A worked example of one review
Imagine a pull request that adds a discount feature. Here is a set of comments that would land well:
- Must fix: "If the discount code is expired, this still applies it, because the date check uses the server's local time. Could we compare in UTC? I added a failing case in a comment below."
- Suggestion: "Optional, but pulling the discount rules into their own function would make them easier to test on their own. Happy either way."
- Nit: "Small one:
calccould becalculateDiscountfor readability." - Question: "What happens if two codes are applied? I could not tell from the ticket whether that is allowed."
- Positive: "The tests for percentage discounts are really clear, thanks."
The author knows exactly what blocks approval (one thing), what is up to them, and that the reviewer read the work properly. That review is unlikely to start an argument.
A self-check before you submit a review
- Is every blocking comment about correctness, security, requirements or agreed standards, rather than my taste?
- Does each comment say why?
- Would I be comfortable if this comment was read aloud in a team meeting?
- Have I said at least one specific thing that is good?
- If I have more than ten comments, should this be a conversation instead?
When you receive feedback yourself
How you take review comments shapes how people give them to you. Reply to each with thanks, a fix, or a reason: "Good catch, fixed" or "I kept this because X, but happy to change it." Engineers who receive feedback gracefully find that others start giving theirs more gracefully too. If a review turns into a real disagreement with someone senior, what to do when you disagree with a senior engineer covers the next step.
If you are still stuck
Read Six rules that keep a codebase worth working in and Twelve moves that take you from mid level to senior, where reviewing others well is a recurring theme. If you want someone to look at your specific situation, join Sefism and, as a member, book a 1:1 session.
Was this answer helpful?
Read next
- Six Rules That Keep a Codebase Worth Working InEvery one of these gets quoted as an acronym in code review, usually by somebody who read the expansion and not the reasoning, and applied without judgement they produce worse code than if nobody had heard of them. Separation of concerns, DRY, KISS, YAGNI, test driven design and writing for the next reader, each with the thing it protects against and the way it goes wrong.
- Twelve Moves That Take You From Mid Level to SeniorGetting to mid level is mostly time and repetition, and then the path stops being clear. The thing that got you here, doing assigned work well, is not what the next level rewards, and nobody says so directly, so capable engineers respond by doing more of what already worked. Twelve heuristics for the part that is not obvious.
- The Habits That Make an Engineer Worth Routing Work ThroughEvery team has one or two engineers other people route work through, and what they have in common is not raw technical strength. It is that when something is given to them it comes back, and when it will not, you hear about it early. Fifteen habits that build that reputation, none of which require a title or permission.
Your situation is not quite this one?
Members get written answers to their own questions, a roadmap built for them and feedback on their projects. Early access is open to X and Instagram followers and university students. Prefer to talk? A free call works too.