Code Review Best Practices

Code review is a skill. Here's what I've learned about doing it well.

#The Goal

Reviews aren't about finding bugs (tests do that). They're about:

• Knowledge sharing
• Catching design issues early
• Maintaining code quality standards
• Teaching and learning

Keep this in mind—it changes how you approach reviews.

#Giving Reviews

#Be Specific

Bad: "This is confusing."

Good: "The variable name data doesn't tell me what it contains. Maybe user_preferences or config_settings?"

Vague feedback creates work. Specific feedback creates action.

#Explain Why

Bad: "Don't use a list here."

Good: "A set would be better here since you're checking membership in a loop. O(1) lookup vs O(n)."

The "why" teaches. It also lets the author push back if they have context you don't.

#Distinguish Severity

Not all feedback is equal:

[blocking] This will break in production because X
[suggestion] Consider using Y for better performance
[nit] Typo in comment on line 42
[question] I don't understand this part—can you explain?

Authors need to know what must change vs what's optional.

#Ask Questions

Sometimes you're wrong. The author might have context you lack.

Instead of: "This is wrong, use X instead."

Try: "Why did you choose this approach over X? I'm curious about the tradeoff."

You might learn something. Or you'll get confirmation that it should change.

#Receiving Reviews

#Don't Take It Personally

The code is not you. Feedback on code is not feedback on your worth.

This is hard. It gets easier with practice.

#Respond to Everything

Even if it's just "Good point, fixed" or "I considered that, but X."

Silent changes leave reviewers wondering if you saw their feedback.

#Push Back When Appropriate

Reviews are a conversation. If you disagree:

1. Explain your reasoning
2. Cite evidence if possible
3. Be open to being wrong

"I thought about that, but I went this way because..." is valuable context.

#Common Antipatterns

#The Drive-By

Dropping "LGTM" without actually reading the code. Don't do this.

#The Novel

Writing paragraphs when a sentence would do. Respect everyone's time.

#The Perfectionist

Blocking on style preferences that don't matter. Pick your battles.

#The Silent Treatment

Never responding to comments. Always close the loop.

#My Checklist

When reviewing, I check:

1. Does it work? Logic, edge cases, error handling
2. Is it readable? Names, structure, comments where needed
3. Is it tested? Happy path and failure cases
4. Is it maintainable? Will future-me understand this?
5. Is it consistent? Does it match the codebase style?

#Speed Matters

Reviews should happen quickly. Blocked PRs kill momentum.

My targets:

• Small PRs: Same day
• Large PRs: Within 24 hours (or acknowledge and schedule)

If you can't review soon, say so. "I'll get to this tomorrow" is better than silence.

#The Best Reviews

The best reviews I've received:

• Taught me something new
• Caught bugs I missed
• Made me think about edge cases
• Were kind about it

The best reviews I've given:

• Were actionable
• Explained the reasoning
• Respected the author's time
• Made the code better without being precious

Code review is collaboration. Approach it that way.