The Art of Code Review: How to Critique Without Being Toxic
Comments
Sign in to join the conversation
Sign in to join the conversation
Code reviews are the lifeblood of a healthy engineering team. They prevent bugs, ensure consistency, and most importantly, facilitate knowledge transfer. However, they are also a common source of friction. We've all received that comment: "Why did you do it this way?" or "Fix this."
Reviewing code is a skill, distinct from writing code. Here is how to master it.
The most common trap senior engineers fall into is trying to make every pull request (PR) look exactly like code they would have written.
The Golden Rule: If the code is correct, performant, readable, and follows the style guide, approve it, even if you would have approached it differently.
reduce function."for loop works, but a reduce might be cleaner here. What do you think?"Offering alternatives as suggestions rather than commands empowers the author to own their code.
Human beings should not be arguing about whitespace, semicolons, or indentation. That is a waste of expensive salary time.
If you find yourself commenting "Add a space here," your tooling has failed you. Invest time in your .eslintrc or GitHub Actions workflow so you never have to make a style comment again.
Not all comments are equal. Explicitly labeling your comments helps the author prioritize.
Example:
[NIT] Variable name
uis a bit vague. MaybeuserorcurrentUser?
Language matters. Avoid "You."
By focusing on "This change" or "The code," you remove the personal attack. The code is an artifact we are working on together; it is not an extension of the author's self-worth.
The old management advice of "Praise, Critique, Praise" can feel manipulative. Instead, just be genuinely appreciative when you see good work.
If you are reviewing a massive, complex PR that clearly took days of effort, start with: "Thanks for tackling this huge refactor! I know it was a beast. I have a few comments below on edge cases, but the architecture looks solid."
Acknowledging effort goes a long way.
Great code reviews are a dialogue, not a lecture. Your job as a reviewer is to be a safety net, not a gatekeeper. By automating the trivial stuff, explicitly categorizing your feedback, and checking your tone, you can turn code reviews from a stressful chore into the best learning tool your team has.