The Art of Code Review: Giving Feedback That Ships Better Code

Code Review Is a Conversation

A code review is not a gate — it's a conversation between peers. The goal isn't to find faults; it's to collectively produce the best code possible.

The Reviewer's Mindset

Before writing any comment, ask yourself:

1. Is this a real issue or personal preference?
2. Am I being specific enough to be actionable?
3. Am I assuming good intent?

Comment Categories

Prefix your comments to set expectations:

• nit: — Style/formatting, non-blocking
• suggestion: — Alternative approach worth considering
• question: — Seeking to understand, not criticize
• blocker: — Must fix before merging

Good vs Bad Feedback

❌ Bad:

"This is wrong."

✅ Good:

"suggestion: This could throw if user is null after the auth check on line 42 fails silently. Consider adding a guard: if (!user) return notFound()"

❌ Bad:

"Why didn't you use X pattern?"

✅ Good:

"question: I'm curious about the choice here — did you consider the strategy pattern? It might simplify adding new payment providers later. Happy to discuss!"

The Author's Responsibilities

• Write a clear PR description (what and why)
• Self-review before requesting review
• Keep PRs focused and under 400 lines
• Respond to all comments (even with "done")
• Don't take feedback personally

Speed Matters

• Review within 4 hours of being requested
• Don't block PRs over style preferences
• If you need context, ask quickly instead of stalling
• Approve with minor comments: "LGTM with nits"

What to Focus On

High value: Logic errors, security issues, missing edge cases, architecture concerns

Low value: Naming bikeshedding, brace style, import ordering (automate these!)

Building Review Culture

• Celebrate good PRs publicly
• Rotate reviewers to spread knowledge
• New team members? Review their code generously, explain the "why"
• Senior devs: request reviews from juniors too

Great code reviews build great teams. Invest in the practice.