Code Review Is Not About Finding Bugs. It Is About Sharing Understanding.

The Review That Passed Everything and Missed the Point

A PR comes in. The logic is correct. The tests cover the cases. The naming is clear. Two reviewers approve. It ships. Six months later, a new engineer modifies the same code without understanding a critical constraint — the function must be called only after a specific initialization sequence, and there's nothing in the code or comments that makes this clear. A bug is introduced. An incident follows.

The code review process found no bugs. It also failed at the more important job: ensuring that the knowledge required to work safely with this code was shared beyond its original author.

This is the gap between reviewing for defects and reviewing for understanding.

What Effective Review Actually Looks Like

The reviewer's primary job is not to approve or reject code. It is to understand what the code is doing well enough to ask useful questions about it. Not "is this correct?" but "do I understand why this decision was made, and would I be able to modify this safely six months from now?"

If the answer is no — if the code works but you don't understand a piece of it — that is a review comment. Not "this is wrong" but "I can't see why this was done this way, can you add a comment explaining it?" That question serves every future reader of the file.

The author's job is not just to produce correct code but to produce code that communicates its intent and its constraints. A PR description that says "implemented the order validation changes" is less useful than one that explains: "Changed from client-side to server-side validation for the discount code field. The previous approach allowed race conditions when two sessions validated the same single-use code concurrently — see issue #2847. Server-side validation uses a row lock; see the comment in DiscountCodeService.validate()."

That context belongs in the PR description and in the code. The review is the opportunity to verify that it's there.

The Knowledge Distribution Problem

Most teams have knowledge concentration — certain engineers who understand certain subsystems deeply, and everyone else who works around them. Code review is one of the few structural mechanisms that can distribute that knowledge.

To use it that way requires reviewers to be assigned (or self-assign) based partly on knowledge gaps. If only the person who built the payment service reviews payment service PRs, the knowledge never spreads. If a backend developer who primarily works on the API layer reviews a payment service PR, they will ask questions the expert reviewer wouldn't think to ask — and the answers to those questions go into comments and documentation that make the codebase more accessible.

This is uncomfortable because it's slower. The payment expert reviews the PR in ten minutes. The API developer reviews it in forty and has five questions. But the forty-minute review produces compounding value; the ten-minute review produces none.

What to Actually Comment On

Things that are correct but not obvious: If the implementation is non-obvious — a specific ordering that matters, a performance constraint that drove the design, a business rule that isn't apparent from the code — ask for it to be documented at the code level.

Missing context on why, not what: Code review comments that restate what the code does ("this sorts the array") are useless. Comments that explain why a non-obvious approach was chosen ("using a stable sort here because UI order must match insertion order for equal-priority items, per the spec in issue #1204") are permanently valuable.

Scope of impact: Does this change have effects beyond what the PR intends? Does it change behavior for existing callers? Does it introduce a new external dependency? Questions about scope and blast radius are often more valuable than questions about implementation details.

Testability of edge cases: Not "does it have tests" but "does it test the specific failure mode that this code is meant to protect against?" A test that verifies the happy path and a test that verifies the constraint the code is enforcing are different things.

What Not to Do

Don't use code review to enforce stylistic preferences that aren't in your team's agreed style guide. This is the most common way code review becomes adversarial. If a naming convention matters, put it in your linter. If it's not in the linter, don't block a PR over it.

Don't nitpick at the expense of the high-signal comments. A PR with twelve minor style comments and no substantive questions communicates that the reviewer did a surface scan, not a deep review.

Don't approve code you don't understand. "Looks good" on code you haven't genuinely understood is not a useful approval. It's abdication.

The Practical Takeaway

Change one thing about how you review PRs: before leaving any comment, ask yourself whether it improves the long-term understandability of the code, or whether it's about a preference. Keep the former, drop the latter. When you finish a review, ask yourself: could you explain to a new team member what this code does and why it was written this way? If not, that's your final comment — a question asking for the explanation you'd need to give it.