The Professional Programmer

Code Reviews and Collaboration

I once received a code review that said "this is wrong" with no explanation. I spent an hour guessing what the reviewer meant. I fixed three different things. The reviewer came back with "still wrong." Turned out they meant a completely different function—one I hadn't touched.

Code reviews can be the best part of working on a team. They can also be demoralizing, slow, and pointless. The difference is how you give and receive feedback.

Code reviews serve multiple goals. If you only focus on one, you'll miss the others.

1. Catch Bugs and Issues

The obvious one. A second pair of eyes finds things you missed. Logic errors. Edge cases. Security holes. Performance problems.

When someone reviews your code, they learn how the system works. When you review theirs, you learn too. Over time, the team develops shared understanding. No one person is the bottleneck.

3. Maintain Consistency

Code style. Patterns. Conventions. Reviews enforce that the codebase feels like one team wrote it, not six individuals.

4. Mentor and Grow

Reviews are teaching moments. "Consider extracting this—here's why" helps the author learn. So does "I didn't know we had a utility for this—good call."

5. Build Collective Ownership

When everyone has reviewed the code, everyone feels responsible for it. That reduces the "not my code" mentality when things break.

Giving Constructive Feedback

The goal is better code and a better author. Not to prove you're smarter.

Describe, Don't Judge

Bad: "This is wrong."
Better: "This loop runs O(n²) — with 10k items that could be slow. Consider using a Set for the lookup."

Bad: "Bad variable name."
Better: "data is vague—could you use userPreferences to match the domain?"

Bad: "Why did you do it this way?"
Better: "I'm curious about the approach here—did you consider X? I might be missing something."

Describe what you see and what you'd suggest. Explain the why. The author can't fix "wrong" — they need to know what's wrong and why it matters.

Use the Right Tone

"Consider..." — Suggestion, not command
"What do you think about..." — Invites discussion
"We usually..." — References team norms
"This might cause..." — Explains impact

Avoid:

"You should..." — Sounds paternal
"Never do..." — Absolute, dismissive
"Obviously..." — Implies they're dumb for not knowing

Prioritize

Not every comment is equal. Distinguish:

Must fix — Bugs, security issues, clear violations of requirements
Should fix — Style, clarity, maintainability—things that matter
Consider — Nice-to-haves, alternative approaches—optional

Label them if your review tool allows. Or use phrasing: "Nit: ..." for minor things, "Important: ..." for must-fix.

Don't drown the author in 50 comments when 5 matter. They'll tune out.

Ask Questions

Sometimes you don't understand. Ask.

"I'm not following the flow here—can you walk me through the logic?"
"Is there a reason we're not using the existing cache layer?"

Questions assume good intent. They invite explanation. The author might have a good reason you hadn't considered.

Receiving Feedback Without Defensiveness

Your code is not you. Criticism of your code is not criticism of you.

This is easy to say, hard to internalize. You spent hours on this. You're proud of it. And now someone is picking it apart.

Separate the Code from Yourself

The reviewer is trying to improve the codebase. They're on your side. They want the same thing you want: good software.

When feedback feels personal, pause. Take a breath. Assume they mean well. Ask for clarification if the tone is unclear.

Understand Before Responding

Don't reply with "no" immediately. Make sure you understand:

What exactly are they suggesting?
What problem are they trying to solve?
Do they have a point?

Sometimes the feedback is wrong. Sometimes you had a good reason they don't know about. But "I did it this way because X" is different from "you're wrong." The first invites dialogue. The second shuts it down.

It's Okay to Disagree

You don't have to accept every suggestion. If you disagree, explain why. "I considered that approach—the trade-off is X. I went with Y because of Z."

The reviewer might learn something. They might change their mind. Or you might agree to disagree and escalate if it matters.

Thank the Reviewer

Even when feedback is critical. "Good catch on the edge case." "I hadn't thought about the performance implication—thanks."

Gratitude makes the next review easier. It signals that feedback is welcome.

Code Review Best Practices

Review Promptly

Nothing kills momentum like a PR that sits for three days. Aim for same-day or next-day reviews. If you can't do a full review, at least acknowledge and give a timeline.

Keep PRs Small

A 2000-line PR is un-reviewable. Nobody can hold that much context. Aim for 200–400 lines. If the feature is big, split it into reviewable chunks.

Provide Context

The PR description should explain:

What this change does
Why (what problem does it solve?)
How to test it
Any decisions that might seem surprising

Reviewers shouldn't have to guess.

Use a Checklist

Customize for your team. Common items:

Code follows team style guide
Tests added/updated for new behavior
No obvious performance issues
Error handling for failure cases
Naming is clear
No debug code or commented-out blocks
Documentation updated if needed

Checklists ensure nothing falls through the cracks. They also make it easier for junior reviewers to contribute.

Review the Right Things

Focus on:

Correctness — Does it do what it's supposed to?
Design — Does it fit the architecture? Is it maintainable?
Readability — Can the next developer understand it?
Tests — Are the right things tested?

Don't waste time on:

Nitpicking style (automate with linters)
Rewriting the author's code in your preferred style
Blocking on preferences when the code is fine either way

Pair Programming as Alternative

Code reviews happen after the fact. Pair programming is a live review—two people at one keyboard, writing code together.

When to Pair

Complex or critical code — Two heads catch more. The cost of a bug is high.
Knowledge transfer — Onboarding, spreading domain knowledge, teaching a technique
Stuck on a problem — Talking through it often unsticks you
High-stakes decisions — Architecture choices, refactors—get alignment early

When Not to Pair

Routine work — CRUD, boilerplate, well-understood tasks
Exploratory work — Sometimes you need to wander alone
When focus is scarce — If your calendar is already fragmented, pairing might not fit

Making Pairing Work

Driver and navigator — One types, one guides. Switch regularly.
Time-box it — Pair for 2 hours, then solo. Avoid pairing fatigue.
Equal participation — The navigator shouldn't just watch. They should think aloud, suggest, question.
Respect different styles — Some people need quiet to think. Pairing isn't for everyone all the time.

Pairing vs. Review: The Trade-off

Pairing catches issues earlier—before the code is written. But it's more expensive (two people for the whole session). Reviews are cheaper but catch issues later.

Use both. Pair for the hard parts. Review the rest. Find the balance that works for your team.

Handling Difficult Reviews

The Nitpicker

Someone who comments on every comma. Redirect: "I'll run the linter and fix style—can you focus on the logic and design?" Or: automate style so there's nothing to nitpick.

The Absent Reviewer

PRs sit for days. Escalate: "I need a review to unblock—can someone take a look?" If it's cultural, raise it in retro. Reviews are part of the job.

The Hostile Reviewer

Rare, but it happens. "This is garbage." Don't engage in kind. "I'd appreciate more specific feedback so I can improve this." If it persists, involve your manager. Hostility isn't a code review problem—it's a people problem.

The Rubber-Stamp

"I'll approve once the tests pass." That's not a review. Gently push: "Could you take a look at the approach? I'm not sure about the error handling." Make it safe to give real feedback.

Key insight: Code reviews serve quality, knowledge sharing, and team cohesion. Give feedback that describes and suggests, not judges. Explain the why. Receive feedback by separating code from self—criticism of your code isn't criticism of you. Keep PRs small, review promptly, use checklists. Pair programming catches issues earlier but costs more—use both. The goal is better software and a stronger team.

Purpose of Code Reviews: Knowledge Sharing and Quality