Code Review Comments That Don't Hurt

A code review is a technical act, but it is read as a personal one. The same fix suggested two ways can land as helpful mentoring or as a public jab. Written comments have no tone of voice, so the reader supplies one — usually the harshest reading. This playbook gives you four templates for the most common review situations. The throughline is simple: comment on the code, never on the coder, and always say why.

"I think there might be a bug here: if `items` is empty, this line divides by zero and the request will crash. Could we add a guard for the empty case? Something like an early return when `items.length === 0` would do it."

Use this when you spot a real defect. Notice three moves: "I think" softens the claim without hiding it, the explanation says exactly what breaks and when, and the suggestion offers a concrete fix instead of just naming the problem. "This is broken" starts a fight; "if items is empty, this divides by zero" starts a fix. Point at the code and the failing case, never at the author's carelessness.

"This works, and I would ship it as is if we are in a hurry. One optional idea for later: we could replace the nested loops with a lookup map, which would drop this from O(n²) to O(n). Totally your call — not a blocker."

Use this for improvements that are nice but not required. The magic words are "optional," "your call," and "not a blocker": they make crystal clear that the author can decline without any drama. Separating preference from requirement is the single most trust-building habit in review. When reviewers dress up every personal taste as a mandate, authors start ignoring all of it. Label the small stuff as small, and your real objections get taken seriously.

"Help me understand the reasoning here — I might be missing context. Why do we cache the token in memory instead of reading it fresh each time? If there is a performance reason I will happily drop this, I just want to make sure we are not risking a stale token after a refresh."

Use this when you suspect a problem but are not sure — which is often. Asking a genuine question does two things at once: it gives the author room to explain a decision you may have misjudged, and it surfaces a real risk if there is one, without accusing anyone. "Why did you do it this way?" can sound like an attack; "help me understand — I might be missing context" invites a conversation. Curiosity ages far better than certainty in a review thread.

"This one I do need us to change before merge: the API key is hard-coded on line 42, which would ship a secret to the public repo. Let's move it to an environment variable. Happy to pair on it if that is quicker. Everything else looks great — the error handling in this PR is genuinely clean."