Knowledge Vault

Code Reviews

3 min read

Code Reviews

A systematic examination of source code by someone other than the original author. Code review is one of the most effective defect-detection practices in software engineering — IBM’s inspection data from the 1970s showed reviews catching 60-90% of defects, and modern studies consistently confirm that peer review outperforms testing alone at finding design-level bugs.

The purpose is not gatekeeping. It is knowledge transfer, defect prevention, and collective ownership of the codebase.

What Makes a Good Review

Small scope. Reviews of 200-400 lines take 60-90 minutes and catch the most defects. Beyond 400 lines, reviewer attention drops sharply — a 1000-line review often gets rubber-stamped because the cognitive load is too high.

Clear context. The PR description should state what changed, why, and how to verify it. Reviewers should not have to reverse-engineer intent from a diff.

Focus on substance. Style issues should be caught by linters, not humans. Reviewer attention is scarce — spend it on logic errors, missing edge cases, security issues, and design problems.

Timely turnaround. Reviews that sit for days block progress and train authors to batch larger changes. Aim for same-day review for PRs under 400 lines.

What to Look For

  • Correctness: Does the code do what it claims? Are edge cases handled?
  • Security: Input validation, authentication checks, injection vulnerabilities
  • Maintainability: Will someone unfamiliar with this code understand it in six months?
  • Testing: Are the tests meaningful? Do they test behavior, not implementation?
  • Architecture: Does this change fit the existing patterns, or introduce a new one without justification?

Giving Feedback

Be specific. “This is confusing” is not actionable. “This function does three things — the retry logic could be extracted to make the happy path clearer” is.

Distinguish blockers from suggestions. Prefix with “nit:” for minor style preferences, “question:” for clarifications, and leave untagged for must-fix issues.

Explain why. “Don’t use string concatenation for SQL” is a command. “String concatenation in SQL queries allows injection attacks — use parameterized queries instead” teaches.

Receiving Feedback

Respond to every comment, even if just “done.” Unexplained changes to address feedback make it hard for the reviewer to confirm the issue was resolved correctly. If you disagree with feedback, explain your reasoning — don’t silently ignore it.

Relationship to Other Practices

Code reviews complement Boy Scout Rule — reviewers can catch opportunities to leave code cleaner. They also enforce naming standards and single responsibility across the team.

Common Mistakes

  • Reviewing only for style while missing logic errors
  • Approving without reading tests
  • Blocking PRs over subjective preferences not covered by the style guide
  • Treating review as a hierarchy (senior reviews junior) rather than a collaborative practice

References

  • Fagan, M. (1976). Design and Code Inspections to Reduce Errors in Program Development. IBM Systems Journal.
  • Cohen, J. (2006). Best Kept Secrets of Peer Code Review. SmartBear Software.
  • Google Engineering Practices documentation (2019). How to do a code review.

Graph View

Backlinks