Best code review comments examples (with do’s and don’ts)

A single comment in a code review can block a pull request for days. The suggestion may be right, but if it is unclear or sounds like an order coming from above, nothing moves. Everyone has seen good intentions turn into frustrating discussions that slow the whole team down. Writing good comments in a code review is a skill that makes you more effective. You learn how to improve the code without breaking the flow of the person who wrote it or creating unnecessary work. In this post I’m going to share some code review comment examples that will help you.

The problem with review comments

Review is supposed to speed up delivery by catching problems early, but a lot of the time the opposite happens. Vague feedback like “refactor this” forces the person who wrote it to guess what the reviewer meant, which leads to rework or a meeting that breaks the rhythm. Comments that sound personal, even when that is not the intention, put the author on the defensive. A blunt “this is wrong” gives a very different impression than “I think this may not cover the case where the user is logged out. What do you think?”. And comments without context leave the person who wrote it without understanding why the change was requested, turning a learning moment into something mechanical, just going through the motions.

A different way to think about comments

A code review process is a conversation, a way to build shared understanding around a change. The goal is to make sure the code is correct and that someone other than the person who wrote it can maintain it. When someone leaves a comment, they are transferring knowledge about an edge case, a system limitation, or a future requirement that may not have been clear. When the person who wrote it responds, they share the context behind the decision. That exchange improves code quality and makes the team more prepared. Every comment becomes a learning opportunity for the person writing and the person reviewing.

Code review comment examples: what to do

Good comments are collaborative. They make room for discussion, not shut it down.

Start with questions, not commands

A question respects authorship and recognizes that there may be context you do not have. It opens up dialogue.

Instead of:

"Add a null check here."

Try:

"What happens if `user.profile` is null here? I’m thinking about newly created users who have not completed their profile yet. Does it make sense to handle that case?"

Instead of:

"Split this function."

Try:

"This function seems to fetch the data and then transform it. Could we split that into two functions? It might make it easier to test the transformation part in isolation."

Explain the “why” behind your suggestion

Connect your feedback to a principle, a future plan, or a team standard. That makes the suggestion sound objective, not like a personal opinion.

Instead of:

"Use `map`."

Try:

"Replacing this `for` loop with a `map` could make it more idiomatic for creating a new array from another one. It also matches the pattern we use in the other service modules."

Instead of:

"Create a helper function."

Try:

"Moving this validation into a helper function could avoid repetition. The `feature-Y` ticket will need the same validation, so we could reuse it."

Offer specific and actionable alternatives

If you see a better approach, show it. That helps more than just pointing out the problem.

Instead of:

"Do not call this service directly."

Try:

"Instead of calling `ServiceA.get()` directly, what if we used `ServiceB.fetchData()`? That method already has cache and retry, so it avoids duplicating that here."

Look at patterns and implications, not just one line

Take a step back and look at the whole thing. A comment that improves the system design is worth more than one that only fixes a detail.

Instead of:

"There is repeated code on lines 42 and 98."

Try:

"I’m seeing this pattern of authenticating the request and then extracting the user ID in a few places in this PR. Maybe we could create a middleware or decorator for that? It could make things cleaner and more consistent."

What to avoid in your comments

Just as important as knowing what to do is knowing what to avoid. These habits only create noise.

Vague or generic comments

• “This is bad.” (Why? What is the impact?)
• “Refactor this.” (Refactor how? What is the specific problem?)
• “This looks weird.” (What exactly looks weird? The name? The structure? The logic?)

Comments that treat personal preference like a rule

If it is not in the team guide and it does not affect how the code works or its readability, it is probably just preference. Forcing that creates rework with no real gain.

• “I always use single quotes here.” (If the linter does not care, let it go.)
• “I do not like this structure, change it.” (It is missing the “why.” Is it harder to maintain? Worse performance? If not, it is just an opinion.)

Prescriptive commands without explanation

Telling someone what to do without explaining why takes away the chance to learn and can come across as disrespectful.

• “Change this to a `switch`.” (Why? Is it more readable? Better performance here? Or is it just style?)
• “Use a factory pattern here.” (Why does that pattern make more sense in this case? What future problem does it solve?)

Ignoring context because of small details

Prioritize your feedback. A PR with N+1 risk does not need five comments about trailing whitespace. In general, follow this order: first, correctness — does the code work and cover edge cases? Then design — does it fit the system and is it easy to maintain? Last, style — does it follow team standards? If there is a serious design problem, start there.