Code Review Roadmap

Code review is how teams check each other's changes before they ship. It catches bugs, but its larger value is shared understanding: more people know each part of the system, the codebase stays consistent, and engineers learn from each other every day. Almost every software job involves reviewing and being reviewed, and many interviews now include a code review exercise or behavioural questions about it.

This roadmap covers both sides. It starts with why review exists and how a pull request moves to merge, then how to prepare changes that are easy to review. It moves on to what to look for: correctness, tests, design, security, performance and operability. Then it covers how to say it: clear, kind, labelled comments and handling disagreement. The final stages cover tooling, AI-assisted review and building a healthy review culture. Core topics are expected of every engineer; recommended ones mark a strong reviewer.

By the end you will be able to review a change thoroughly and quickly, write comments people act on, and answer review questions in interviews. Practise reading code critically in coding practice and track your progress in progress page.

Level
Beginner to advanced
Time
8–12 weeks at about 4 hours a week, alongside real reviews
Scope
54 topics in 8 stages
Before you start
Working knowledge of at least one programming language and its testing tools; Basic Git and GitHub Roadmap: branches, commits and pull requests; Some experience of working in a shared codebase, even a small one

What you will be able to do

  • Prepare small, well-described changes that reviewers can approve quickly.
  • Review a change systematically, from purpose and design down to details.
  • Find correctness, security, performance and operability problems before they ship.
  • Judge tests, interfaces and migrations for risk and backward compatibility.
  • Write clear, kind, labelled comments and resolve disagreements constructively.
  • Use automation, branch protection and AI tools so humans focus on judgement.
  • Perform well in code review interviews and answer behavioural questions about review.

The roadmap at a glance

  1. Stage 1Foundations of Code ReviewBeginner · 1 week · 6 topics
  2. Stage 2Being a Good AuthorBeginner · 1–2 weeks · 7 topics
  3. Stage 3Reviewing for CorrectnessIntermediate · 2 weeks · 7 topics
  4. Stage 4Reviewing Design and MaintainabilityIntermediate · 2 weeks · 7 topics
  5. Stage 5Security, Performance and OperationsIntermediate · 2 weeks · 6 topics
  6. Stage 6Communicating in ReviewIntermediate · 2 weeks · 8 topics
  7. Stage 7Tools and AutomationIntermediate · 1–2 weeks · 6 topics
  8. Stage 8Scaling Review and Interview ReadinessAdvanced · 1–2 weeks · 7 topics

Stage 1 Foundations of Code Review

Beginner1 week6 topics

Goal. Explain why teams review code, the forms review takes, and how a change moves from draft to merge.

Why Code Review Exists Core

Code review is a second engineer reading a change before it joins the main branch. Catching bugs is only one of its jobs, and often not the biggest. Review also spreads knowledge so more than one person understands each part of the system, keeps the codebase consistent, mentors less experienced engineers, and creates a written record of why a change was made.

It is not a gate to prove the author wrong, a style contest or a substitute for testing. Automated checks catch formatting and many defects more cheaply. A reviewer's attention is best spent on things machines cannot judge: whether the change solves the right problem, whether its design will age well, and whether the next engineer will understand it.

Practice. Write down the three outcomes your team most wants from review and check whether recent review comments served them.

Types of Review Core

Review takes several forms, and teams often mix them.

  • Asynchronous pull or merge requests: the default in most companies. The author opens a change, reviewers comment in a tool such as GitHub, GitLab, Bitbucket or Gerrit, and the change merges once approved.
  • Pair and mob programming: review happens continuously while the code is written; many teams treat paired code as already reviewed.
  • Over-the-shoulder walkthroughs: the author explains a change live. Fast, but leaves little written record.
  • Formal inspections: scheduled meetings with checklists and roles, still used in safety-critical fields such as aviation and medical devices.

Choose by risk and speed: a typo fix needs a quick glance, while a payments change may warrant a walkthrough plus written review.

Practice. List the last ten changes you made and decide which form of review would have suited each.

Roles and Responsibilities Core

Clear roles stop review from becoming either a rubber stamp or an endless debate.

  • The author owns the change: its correctness, its tests, its description and getting it merged. Review does not move that ownership to someone else.
  • The reviewer owns their verdict: they say what they checked, what worries them and whether it is ready.
  • Code owners are people or teams responsible for an area. A CODEOWNERS file in GitHub or GitLab requests them automatically and can require their approval.
  • A maintainer or tech lead settles disagreements when author and reviewer cannot.

If several reviewers are tagged, say who should review what, or everyone assumes someone else looked closely.

Practice. Draft a CODEOWNERS file for a repository you know, assigning each top-level folder to a person or team.

The Pull Request Lifecycle Core

A typical change moves through clear states.

  1. Draft: the author pushes early work, often to get CI running or to ask for direction.
  2. Ready for review: description complete, checks green, reviewers assigned.
  3. Review rounds: comments, replies and new commits until reviewers approve.
  4. Merge: by merge commit, squash or rebase, depending on team policy, often after a final CI run on the up-to-date branch.
  5. Deploy and verify: the author checks the change works in production.

Most delays hide between states: a change waiting a day for its first review, or approved but never merged. Make each hand-off visible and treat a waiting review as blocked work.

Practice. Trace one of your recent pull requests through each state and note how long it waited at each hand-off.

Team Review Agreements Recommended

Most review friction comes from unspoken expectations. Write a short team agreement covering:

  • How many approvals a change needs, and from whom.
  • Expected turnaround, such as a first response within one working day.
  • Size limits and when to split a change.
  • What blocks a merge and what is optional, and how comments are labelled.
  • Who merges: the author after approval, or the reviewer.
  • What can skip review, if anything, such as emergency fixes with review afterwards.

Keep it to one page, store it in the repository, and revisit it when people complain. An agreement turns personal arguments into a shared rule that anyone can point to.

Practice. Write a one-page review agreement for your team and ask two colleagues what they would change.

Review Speed and Turnaround Core

Slow review is one of the biggest drags on a team's delivery. While a change waits, the author switches to other work, conflicts pile up and the context fades for everyone. Fast review is a habit, not heroics.

  • Treat review requests as higher priority than starting new work of your own.
  • Check for reviews at natural breaks, such as after lunch or a meeting, rather than letting them interrupt deep work.
  • Aim to respond within a few working hours; a first response matters even if the full review comes later.
  • If you cannot review soon, say so and suggest someone else.

Speed should come from small changes and good descriptions, not from skimming.

Practice. Measure the median time to first review on your team for a month and agree one change to reduce it.

Stage 2 Being a Good Author

Beginner1–2 weeks7 topics

Goal. Prepare changes that are easy to review and handle feedback professionally.

Small, Focused Changes Core

The single biggest improvement to review quality is smaller changes. Reviewers find more problems in a 150-line change than in a 1,500-line one, because attention fades and big diffs get a quick skim and an approval.

A focused change does one thing: one feature slice, one bug fix or one refactoring. Split mixed work:

  • Refactoring separate from behaviour changes.
  • Mechanical changes, such as renames or formatting, in their own change.
  • Database migrations before the code that uses them.
  • New code behind a feature flag, merged in steps, rather than a long-lived branch.

There is no hard limit, but if you cannot describe the change in one sentence, it is probably two changes.

Practice. Take your largest recent change and plan how it could have been split into three to five smaller ones.

Writing a PR Description Core

A good description lets a reviewer understand the change before reading code, and it becomes documentation for whoever runs git blame later.

## Why
Checkout times out for carts over 50 items (ticket SHOP-812).

## What
- Batch price lookups into one query instead of one per item
- Add an index on prices(product_id, region)

## How to test
Run `make seed-large-cart`, then check out; p95 drops from 9s to 0.4s locally.

## Risks
Index build locks writes briefly; run the migration off-peak.

Include screenshots for UI changes, link the ticket, point reviewers at the trickiest file, and say what you are unsure about.

Practice. Rewrite the description of a past pull request using the why, what, how to test and risks structure.

Self-Review Before Requesting Core

Review your own diff in the review tool before asking anyone else. Seeing the change as a diff, not in your editor, reveals things you missed: debug prints, commented-out code, unrelated formatting, missing tests and confusing names.

A short self-review checklist:

  • Does every changed line belong to this change?
  • Do the tests cover the new behaviour and at least one failure case?
  • Do CI checks pass?
  • Would a reader understand the tricky parts without asking me? If not, improve the code or add a comment.
  • Have I added a review comment on anything I want specific eyes on?

Self-review respects the reviewer's time, and most authors find several problems this way.

Practice. Before your next three pull requests, self-review in the tool and count the issues you fix yourself.

Commit Hygiene Recommended

Commits tell the story of a change. Clean commits make review easier, especially for larger changes reviewed commit by commit.

  • Each commit should build and pass tests on its own, which keeps git bisect useful.
  • Write messages with a short imperative summary line and a body that explains why.
  • Many teams use Conventional Commits prefixes such as feat: and fix: to drive changelogs.
  • Before review, tidy work-in-progress commits with an interactive rebase; after review starts, add new commits so reviewers can see what changed since their last pass.

Whether the branch is squashed on merge is a team decision; know your team's choice. The Git and GitHub Roadmap covers the commands.

Practice. Clean up a messy branch into logical commits that each pass the tests, then compare how easy each is to review.

Stacked Changes Optional

Stacked changes split a large piece of work into a chain of small dependent pull requests, each building on the previous one. Reviewers look at each layer separately while the author keeps working on the next.

For example: first a database migration, then a repository method, then the API endpoint, then the UI. Each is small and reviewable, and earlier layers can merge while later ones are still in review.

The cost is rebasing: when an early change gets feedback, later ones must be updated. Gerrit and Phabricator were built around stacks, and tools such as Graphite, ghstack, git-branchless and Sapling make stacking easier on GitHub. Feature flags let partial work merge without being visible.

Practice. Implement a small feature as a stack of three dependent pull requests and rebase the stack after a change to the first.

Choosing Reviewers Recommended

Pick reviewers for what the change needs, not just whoever is free.

  • Someone who knows the affected code well, for correctness.
  • A code owner, if the area requires one.
  • A specialist for security, database or accessibility changes.
  • Occasionally a newer team member, so knowledge spreads.

One or two reviewers is usually right. Tag five and each assumes the others are checking. If you need specific input from someone, say exactly what: could you check the locking in reserve()? Rotating reviewers or using automatic assignment avoids one senior engineer becoming a bottleneck.

Practice. For your next change, name each reviewer's specific focus in the description.

Responding to Feedback Core

How you respond shapes how people review your code next time.

  • Assume good intent. A blunt comment is usually haste, not hostility.
  • Reply to every comment: fixed, will do in a follow-up (with a ticket), or a reasoned disagreement.
  • If a reviewer was confused, fix the code or add a comment, rather than only explaining in the thread; the next reader will be confused too.
  • Do not argue style the team has already settled; follow the convention.
  • When a thread passes two or three rounds, talk in person or by call, then write the outcome in the thread.
  • Push fixes as new commits and say which commit addressed what.

Thank people for catching real problems.

Practice. On your next reviewed change, reply to every comment and resolve one disagreement with a short call.

Stage 3 Reviewing for Correctness

Intermediate2 weeks7 topics

Goal. Review a change systematically, find real defects, and judge whether its tests are good enough.

Reviewing in Order Core

Read a change in passes, from the biggest questions to the smallest, so you do not spend an hour on naming in code that should not exist.

  1. Purpose: read the description and ticket. Is this change needed, and is it the right approach?
  2. Shape: look at which files changed and the overall design. Is the logic in the right place?
  3. Core logic: read the most important file closely first, often not the first file the tool shows.
  4. Tests: do they prove the behaviour and failure cases?
  5. Details: naming, comments, small simplifications.

If pass one or two reveals a fundamental problem, stop and say so. Line comments on a design you are about to reject waste everyone's time.

Practice. Review a colleague's change using the five passes and note which pass produced your most important comment.

Understanding Intent Core

You cannot judge whether code is correct until you know what it is meant to do. Before reading lines, make sure you understand the requirement, the user-facing behaviour and the constraints.

If the description is thin, ask for more before reviewing deeply. Check the ticket or design document. For behaviour changes, run the branch locally or open the preview environment and try it, including obvious misuse.

Then compare intent and implementation: does the code do what was asked, all of it, and nothing extra? Scope creep is common: a bug fix that also reshapes an unrelated module deserves its own change. Missing pieces, such as a forgotten permission check or a missing mobile layout, are easy to overlook when you only read what is there.

Practice. For your next review, write one sentence describing the intended behaviour before opening the diff, then check the code against it.

Correctness and Edge Cases Core

Most bugs live at the edges. Read each function asking what inputs could break it:

  • Empty, null or missing values; empty lists; zero.
  • Boundaries: first and last items, off-by-one loops, inclusive versus exclusive ranges.
  • Very large inputs, long strings, Unicode and special characters.
  • Time zones, daylight saving changes and leap years.
  • Money rounding and floating-point comparison.
  • Duplicate or out-of-order events and repeated requests.
# reviewer: what happens when items is empty?
average = sum(i.price for i in items) / len(items)

Do not only trust the happy path in the tests. Pick two or three awkward inputs and trace them through the code in your head or by running it.

Practice. Take a function from an open pull request and list five edge-case inputs, then check whether each is handled and tested.

Error Handling and Failure Modes Core

Ask what happens when things go wrong, because production will find out.

  • Are errors from databases, networks and third-party calls handled, or silently swallowed in an empty catch?
  • Do remote calls have timeouts? Are retries limited and only on safe operations?
  • If the operation fails halfway, is data left inconsistent? Is there a transaction or a compensating step?
  • Do error messages help the user without leaking internals such as stack traces?
  • Are failures logged with enough context to debug, at the right level?

A useful habit: for each external call in the diff, ask what the code does if it is slow, fails, or succeeds but the reply is lost.

Practice. Review a change that calls an external service and write down its behaviour for a timeout, an error and a lost reply.

Concurrency and Shared State Recommended

Concurrency bugs rarely show up in tests and are expensive in production, so they deserve slow reading.

  • Check-then-act races: reading a value, deciding, then writing, while another request does the same. Common in stock reservation and unique sign-ups. Fix with database constraints, atomic updates or locks.
  • Shared mutable state: module-level variables, caches and singletons modified by several threads or requests.
  • Lost updates: two users editing the same record; use version numbers or ETag checks.
  • Async pitfalls: missing await, unhandled promise rejections, blocking calls on an event loop.
  • Deadlocks from inconsistent lock ordering.

Ask the author what happens if the same request runs twice at the same moment.

Practice. Find a check-then-act sequence in a codebase you know and propose a fix using a constraint or atomic update.

Reviewing Tests Core

Tests deserve the same attention as production code, because a weak test gives false confidence.

  • Does a test exist for each new behaviour and for the bug being fixed? A bug fix should come with a test that failed before it.
  • Do tests check outcomes, or only that the code ran without errors?
  • Would the test fail if the logic were wrong? Mentally break the code and ask.
  • Are failure and edge cases covered, not only the happy path?
  • Are tests independent, deterministic and fast, without sleeps or reliance on ordering?
  • Is mocking so heavy that the test only checks the mocks?

Coverage percentages are a weak signal; read what the tests actually assert.

Practice. In one pull request, change a line of logic locally and see whether any test fails; report what you find.

Data, Migrations and Configuration Recommended

Some changes are hard to undo, and they need extra care.

  • Schema migrations: will they lock a large table? Are they backward compatible with the code still running during deployment? Prefer expand and contract: add the new column, migrate, switch code, then remove the old one in a later change.
  • Data migrations: are they idempotent, batched and tested on realistic volumes?
  • Configuration: new environment variables documented and set in every environment? Defaults safe?
  • Feature flags: who switches them, and is there a plan to remove them?

Ask for the rollback plan. If the answer is that there is none, the change needs another look.

Practice. Review a migration and write down how it behaves while old and new application versions run side by side.

Stage 4 Reviewing Design and Maintainability

Intermediate2 weeks7 topics

Goal. Judge whether a change fits the system's design and will be easy for the next engineer to change.

Design and Architecture Fit Core

Ask whether the change belongs where it is and fits the patterns the system already uses.

  • Is logic in the right layer, such as business rules in the domain rather than in a controller or SQL view?
  • Does it respect module boundaries, or reach into another module's internals or database tables?
  • Does it introduce a new pattern, library or approach when an established one exists?
  • Does it add coupling that will make future changes harder?

Design concerns are the most valuable comments a reviewer can make, but they come too late if the code is finished. For larger work, encourage a short design note or early draft review before implementation. The Software Design and Architecture Roadmap covers the principles behind these judgements.

Practice. Review a change only for design fit, ignoring details, and write one comment about where its logic should live.

Readability and Naming Core

Code is read many more times than it is written, so readability is a correctness concern for the future. The reviewer is the first test reader: if you have to puzzle over a section, the next engineer will too.

  • Do names say what things are and do? Is data or process hiding meaning?
  • Are functions short enough to follow, at one level of abstraction?
  • Is control flow simple, without deep nesting or clever tricks?
  • Are magic numbers named and booleans avoided as unexplained arguments?

Phrase readability comments from your experience: I had to read this three times to see that it skips archived users; could a helper named activeUsers make that clear?

Practice. Find the hardest-to-read function in an open change and suggest one concrete rename or extraction.

Complexity and Over-Engineering Core

Reviewers often catch the opposite of messy code: code that is more complex than the problem.

  • Abstractions with a single implementation and no realistic second one.
  • Configuration options and extension points nobody asked for.
  • Generic frameworks built for one use case.
  • Clever one-liners that save lines but cost understanding.
  • New dependencies for something the standard library does.

Ask what problem each layer solves today. You are not going to need it is a fair review comment when backed by a reason. Equally, flag missing structure where code is clearly about to grow, such as a third copy of the same branching logic.

Practice. Find one abstraction in a recent change that has a single use and suggest how to inline it.

Duplication and Reuse Recommended

Reviewers often know code the author has not seen. Point out existing helpers, components and utilities that already solve part of the problem; this keeps the codebase smaller and consistent.

Judge duplication carefully. Copies of the same business rule are dangerous, because one will be updated and the other forgotten. Two similar-looking blocks that serve different purposes may be better left separate; merging them couples things that should change independently.

When you suggest reuse, link to the existing code and explain the benefit. When you see a third copy of something, suggest extracting it, possibly in a follow-up change so this one stays focused.

Practice. In your next three reviews, search the codebase for an existing helper before approving any new utility function.

Comments and Documentation Recommended

Check that comments explain why, not what. The code already says what it does; comments should capture reasons, constraints and surprises that the code cannot.

# bad: restates the code
# increment retry count
retries += 1

# good: explains a non-obvious reason
# provider rate-limits per minute; wait for the next window, not a fixed delay

Also check that outdated comments were updated, public APIs have doc comments, the README or runbook changed if setup or operations changed, and that architectural decisions are recorded. If a reviewer needs an explanation in the thread, that explanation usually belongs in the code or docs.

Practice. Find three comments in a codebase that restate the code and either delete them or rewrite them to explain why.

Interfaces and Breaking Changes Core

Changes to anything other code depends on need extra scrutiny: public functions, REST or gRPC endpoints, event schemas, database columns read by other services, CLI flags and configuration keys.

  • Is the change backward compatible? Removing or renaming a field, changing a type or tightening validation breaks callers.
  • Is the new interface consistent with existing ones in naming, errors and pagination?
  • Is it the smallest interface that meets the need? Every public element is a long-term promise.
  • Are consumers known and informed, and is there a deprecation path?

Interfaces are cheap to change before merge and expensive afterwards, so this is where reviewers add the most lasting value. The API Design Roadmap goes deeper.

Practice. Review an API change and list every consumer that could be affected and how.

Dependencies Recommended

A new dependency is a long-term commitment: you inherit its bugs, vulnerabilities, licence and upgrade cycle. Review additions to package manifests deliberately.

  • Is it needed, or would the standard library or an existing dependency do?
  • Is it maintained, widely used and from a trustworthy source? Check for typosquatted names.
  • Is its licence compatible with your product?
  • How large is it, and how many transitive dependencies does it pull in?
  • Is the version pinned and the lock file updated?

Upgrades deserve review too: read the changelog for breaking changes rather than approving an automated bump because CI passed.

Practice. Audit the last three dependencies added to a project against these questions.

Stage 5 Security, Performance and Operations

Intermediate2 weeks6 topics

Goal. Spot common security, performance and operability problems before they reach production.

Security Review Basics Core

Every reviewer should catch the common security mistakes, even without being a specialist.

  • Authorisation: does each endpoint check that this user may access this specific object, not just that they are logged in?
  • Injection: is user input concatenated into SQL, shell commands, HTML or file paths? Use parameterised queries and encoding.
  • Secrets: keys or passwords committed to code or printed in logs.
  • Input validation at trust boundaries, with size limits.
  • Sensitive data exposed in responses, URLs or error messages.
  • Unsafe deserialisation and server-side requests to user-supplied URLs.
  • Cryptography: hand-rolled schemes or outdated algorithms.

For authentication, payments and data export, request a review from a security specialist.

Practice. Review an endpoint you know for object-level authorisation and injection, writing down exactly where each check happens.

Performance in Review Recommended

Reviewers can catch performance problems cheaply before they ship. Look for:

  • Database queries inside loops, the N+1 pattern.
  • Queries on new filters or sorts with no supporting index.
  • Loading whole tables or files into memory, or unbounded result sets.
  • Nested loops over large collections where a map lookup would do.
  • Synchronous calls to slow services in a request path.
  • Missing pagination, caching or timeouts.

Keep it proportionate. Do not demand micro-optimisations in code that runs once a day. Ask about expected data sizes, and request a benchmark or query plan when a change touches a hot path.

Practice. Find an N+1 query or loop-heavy code in a pull request and suggest a fix with an estimate of the saving.

Observability and Operability Recommended

Ask how the team will know whether this change works in production and how they will debug it when it does not.

  • Are important events logged with structured context, such as request ID and user ID, without logging secrets or personal data?
  • Are log levels sensible, so production is not flooded with debug output?
  • Are new endpoints and jobs covered by metrics, traces and alerts?
  • Is the change behind a feature flag so it can be switched off without a deploy?
  • Do the runbook and dashboards need updating?

A change that cannot be observed is a change you will debug blind at three in the morning.

Practice. For a recent change, list the signals that would tell you it broke in production, and add any that are missing.

Privacy and Data Handling Recommended

Review how a change collects, stores and shares personal data.

  • Does it collect only what is needed?
  • Is personal data kept out of logs, analytics events, URLs and error reports?
  • Is sensitive data encrypted and access-controlled?
  • Does a new copy of data, such as a cache, export or third-party integration, respect deletion requests and retention rules?
  • Are test fixtures free of real customer data?

Regulations such as GDPR make these mistakes costly, and they are much easier to prevent in review than to clean up after data has spread.

Practice. Search a codebase's log statements for personal data such as emails or names and propose masked alternatives.

Accessibility and User Experience Optional

For front-end changes, review what the user experiences, not only the code.

  • Run the branch or preview and use the feature yourself, including loading, empty and error states.
  • Can it be used with a keyboard alone? Is focus visible and in a sensible order?
  • Do images have alt text, form fields labels, and buttons accessible names?
  • Is colour contrast sufficient, and is information not conveyed by colour alone?
  • Does the layout work on a narrow phone screen?
  • Are user-facing strings clear and ready for translation?

Screenshots or short recordings in the description make this much faster to review.

Practice. Review a UI change using only the keyboard and a screen reader for five minutes and record what fails.

Rollout and Backward Compatibility Recommended

During deployment, old and new versions run side by side, and clients may be on older versions for weeks. Reviewers should think beyond the merge.

  • Can the new code read data written by the old code, and the reverse?
  • Will mobile apps or other services still using the old contract break?
  • Does the change need a staged rollout, a feature flag or a canary release?
  • Can it be rolled back safely, or does it make a one-way data change?
  • Is the order of deployment across services important?

Ask the author to state the rollout and rollback plan in the description for anything risky.

Practice. Write a rollout and rollback plan for a change that renames a database column used by two services.

Stage 6 Communicating in Review

Intermediate2 weeks8 topics

Goal. Write review comments that are clear, kind and actionable, and resolve disagreements well.

Questions to Ask Core

Good reviewers carry a short list of questions to ask of every change, which keeps reviews thorough without a long checklist.

  • What problem does this solve, and is this the simplest way to solve it?
  • What happens with empty, huge, duplicate or malicious input?
  • What happens when a dependency is slow or fails?
  • Who else depends on what changed?
  • How do we know it works: which test would fail if it broke?
  • How will we know it is working in production, and how do we undo it?
  • Will someone new to this code understand it in six months?

Asking questions in comments, rather than issuing orders, also invites the author to explain context you may lack.

Practice. Turn these questions into a personal review note and use it on your next five reviews.

Writing Clear Comments Core

A useful comment says what you noticed, why it matters and what you suggest.

Weak:   This is wrong.
Better: If `items` is empty this divides by zero and returns a 500.
        Could we return 0 early, and add a test for the empty cart?
  • Point to the exact line and give a concrete example or input.
  • Explain the reason, so the author learns the principle, not just the fix.
  • Offer a suggestion, using the tool's suggested-change feature for small edits.
  • One issue per comment, so each can be resolved separately.
  • If the same issue appears many times, comment once and say it applies throughout.

Practice. Rewrite five of your past review comments so each states the issue, the reason and a suggestion.

Tone and Kindness Core

Written comments lose tone, and the author has put effort into the work. Small wording choices decide whether review feels collaborative or hostile.

  • Comment on the code, not the person: this function, not you forgot.
  • Ask rather than command when you might be missing context: what do you think about…?
  • Avoid words like just, obviously and simply, which imply the author should have known.
  • Do not use sarcasm or rhetorical questions.
  • Be direct about real problems; kindness is not vagueness.

Kind review is not soft review. A clear, respectful comment about a serious bug is the kindest thing you can write.

Practice. Read your last ten review comments as if you were a new junior engineer, and rewrite any that would sting.

Comment Severity Labels Recommended

Authors cannot tell whether a comment blocks merging unless you say. Label each one.

  • Blocking or issue: must change before merge, such as a bug or security hole.
  • Suggestion: worth considering; the author decides.
  • Nit: a minor preference; fine to ignore.
  • Question: you want to understand, not necessarily change.
  • Praise: something done well.

The Conventional Comments format formalises this with prefixes such as issue (blocking): and nitpick (non-blocking):. If most of your comments are nits, consider whether they belong in a linter rule instead.

Practice. Label every comment in your next three reviews and ask the authors whether it changed how they responded.

Approve, Comment or Request Changes Core

Review tools offer three verdicts, and using them consistently keeps work moving.

  • Approve when the change is good enough to merge, even if not perfect. You can approve with optional suggestions.
  • Comment when you have questions or partial feedback and are not ready to judge.
  • Request changes when something must be fixed before merging, and say exactly what.

The standard to apply is whether the change improves the overall health of the codebase, not whether it matches how you would have written it. Holding out for perfection slows the team and discourages small changes. When you request changes, return quickly to re-review once they are made.

Practice. Review three changes and, for each, write one sentence justifying your verdict against the codebase-health standard.

Handling Disagreement Core

Disagreements in review are normal and healthy, but long comment wars are not.

  1. Separate facts from preferences. A bug is a fact; a naming style the team has not agreed is a preference, and the author's choice should usually win.
  2. Use data and principles: a failing test, a benchmark, the style guide or an agreed design.
  3. After two rounds of back and forth, move to a call or chat. Record the decision in the thread.
  4. If you still disagree, escalate to the tech lead or code owner, without making it personal.
  5. If it is not important, let it go, perhaps with a follow-up ticket.

Disagree and commit: once decided, support the outcome.

Practice. Recall a review disagreement you had and write how each of the five steps would have applied.

Giving Praise Recommended

Review comments tend to be all criticism, which teaches authors to dread review. Point out what is done well: a clear test, a tidy refactoring, a careful edge case, a helpful description.

Praise should be specific, so it reinforces the behaviour: splitting the migration into its own change made this easy to check teaches more than nice. It also signals to newer team members which practices the team values.

Do not invent praise to soften criticism; people notice. Give it when it is real, which on a healthy team is often.

Practice. In each of your next five reviews, leave at least one specific comment about something done well.

Mentoring Through Review Recommended

Review is one of the main ways engineers learn a codebase and a craft.

  • When reviewing a junior engineer, explain the reason behind each comment and link to examples in the codebase. Limit yourself to the most important points so the lesson is clear.
  • Offer a pairing session when a change needs many comments; ten written comments can feel crushing where a twenty-minute call feels supportive.
  • Invite juniors to review your code. They learn from reading it, and their questions reveal unclear parts.
  • When reviewing a senior engineer's code, still comment honestly; seniority does not make code correct.

Practice. Ask a less experienced colleague to review your next change and discuss their questions afterwards.

Stage 7 Tools and Automation

Intermediate1–2 weeks6 topics

Goal. Automate the mechanical parts of review and use review platforms and AI tools effectively.

Automate the Boring Parts Core

Anything a machine can check should not take a human reviewer's time. Run these in CI on every pull request, and locally in pre-commit hooks:

  • Formatters such as Prettier, Black, gofmt or rustfmt, so style is never discussed.
  • Linters such as ESLint, Ruff, Pylint, golangci-lint or Checkstyle.
  • Type checking with TypeScript, mypy or the compiler.
  • Unit and integration tests, with results shown on the pull request.
  • Build and dependency checks.

When the same human comment appears repeatedly, turn it into a lint rule. Reviewers then focus on design, correctness and clarity.

Practice. Find a comment you have written three times or more in reviews and turn it into an automated check.

Static Analysis and Security Scanning Recommended

Deeper automated tools find classes of bugs that humans miss.

  • Static analysis: SonarQube, CodeQL and Semgrep find null dereferences, resource leaks, unreachable code and suspicious patterns.
  • Security testing: static application security testing flags injection and unsafe APIs.
  • Dependency scanning: Dependabot, Renovate and similar tools report vulnerable packages and open upgrade pull requests.
  • Secret scanning: detects committed keys before they reach the main branch.

Tune them: tools that raise many false positives get ignored. Show findings as inline comments on the diff, and block merging only on high-confidence, high-severity results.

Practice. Add one static analysis tool and secret scanning to a project's CI, and triage the first batch of findings.

Review Platform Features Recommended

Learn the review tool your team uses; small features save a lot of time.

  • Suggested changes: propose an exact edit the author can apply with one click.
  • Viewed checkboxes and changes since last review, so you only reread what changed.
  • Draft pull requests for early feedback.
  • Pending reviews: batch your comments and submit them together rather than one notification per comment.
  • Templates for pull request descriptions.
  • Checking out the branch locally to run and debug the code.

Gerrit, used by projects such as Android and Chromium, reviews each commit as its own change with numbered patch sets, a different model from GitHub's branch-based pull requests.

Practice. Use suggested changes, viewed checkboxes and a pending review in your next review, and add a description template to a repository.

Branch Protection and Required Reviews Recommended

Branch protection rules enforce the review process instead of relying on memory.

  • Require at least one approval, or two for sensitive repositories.
  • Require approval from code owners for their areas.
  • Require CI checks to pass and the branch to be up to date before merge.
  • Dismiss stale approvals when new commits are pushed, if your team wants that.
  • Block force pushes and deletion of the main branch.
  • Use a merge queue on busy repositories so each change is tested against the latest main.

Rules also matter for compliance: regulated companies often must show that every production change was reviewed by someone other than the author.

Practice. Configure branch protection on a test repository with required reviews, code owners and status checks.

AI-Assisted Review Recommended

AI review tools now comment on pull requests automatically, summarise changes and suggest fixes. They are useful for a first pass: spotting obvious bugs, missing null checks, inconsistent naming and missing tests, and for summarising a large diff before a human reads it.

Their limits matter. They lack context about your business rules and history, can be confidently wrong, and tend to produce many low-value comments. Treat their output like a linter's: helpful hints that a human judges. The human reviewer stays accountable for the approval.

Set expectations as a team: which tool, whether its comments must be answered, and how to turn off noisy categories. The AI-Assisted Coding Roadmap covers these tools more broadly.

Practice. Run an AI review tool on three past pull requests and compare its findings with what human reviewers caught.

Reviewing AI-Generated Code Recommended

More code is now written with AI assistants, which changes what reviewers should look for. Generated code often looks polished but can contain invented APIs, subtle logic errors, outdated patterns, insecure defaults, needless complexity and tests that assert the wrong thing.

Practical rules:

  • The author must understand and own every line, whoever or whatever typed it. Ask them to explain anything unclear.
  • Check that imported functions and library options actually exist.
  • Be wary of very large changes produced quickly; ask for them to be split.
  • Read generated tests closely: do they test behaviour, or simply mirror the implementation?

The standard for merging stays the same.

Practice. Generate a small feature with an AI assistant, then review it as you would a colleague's and list every issue you find.

Stage 8 Scaling Review and Interview Readiness

Advanced1–2 weeks7 topics

Goal. Improve review across a team, handle difficult reviews, and perform well in code review interviews.

Review Checklists Recommended

A short checklist makes review more consistent, especially for high-risk areas. Keep it brief and specific to your system, not a generic list of fifty items nobody reads.

[ ] Purpose clear; linked ticket
[ ] Authorisation checked per object
[ ] Errors and timeouts handled for external calls
[ ] Tests cover new behaviour and one failure case
[ ] Migration safe with old and new code running
[ ] No secrets or personal data in logs
[ ] Rollback plan for risky changes

Put it in the pull request template so authors check themselves first. Review the checklist after incidents: if a bug slipped through review, ask whether a checklist line would have caught it, and remove lines that never do.

Practice. Write a seven-item checklist for the riskiest area of a system you know and add it to the pull request template.

Reviewing Large Changes and Legacy Code Recommended

Sometimes a large change is unavoidable, such as a framework upgrade or generated code. Strategies:

  • Ask the author for a walkthrough call and a guide to which files matter.
  • Ask for mechanical and meaningful changes to be in separate commits, and review them separately.
  • Review generated or vendored files by checking how they were produced, not line by line.
  • Split the review between people by area, and say who covered what.

In legacy code, separate pre-existing problems from new ones. Do not block a small fix because the surrounding file is messy; suggest a follow-up instead. Do insist that new code does not make things worse.

Practice. Review a large change by first asking for a file-by-file guide, then compare your confidence with a cold read.

Reviewing Unfamiliar Code Recommended

You will be asked to review code in areas you do not know. You can still add value.

  • Read the surrounding code and tests before the diff to learn the conventions.
  • Focus on what you can judge: clarity, tests, error handling and edge cases.
  • Ask questions openly; they reveal unclear code and teach you the area.
  • Say what you did and did not check, for example reviewed logic and tests; not qualified to judge the Kafka settings, so an expert can be added.

An honest partial review is better than a confident approval of things you did not understand.

Practice. Review a change in an unfamiliar part of the codebase and state explicitly what your approval covers.

Review Metrics Optional

Metrics help spot process problems, but they are easy to misuse.

  • Time to first review and time to merge: long waits signal overloaded reviewers or oversized changes.
  • Pull request size: trends toward huge changes predict poorer review.
  • Review load per person: is one senior engineer reviewing everything?
  • Escaped defects: bugs found in production that review might have caught.

Never rank individuals by comment counts or approvals; people will game it with trivial comments or rubber stamps. Use metrics to start team conversations, not to judge people.

Practice. Collect time to first review and change size for your team's last 50 pull requests and discuss one finding with the team.

Building a Review Culture Recommended

Healthy review culture is something a team builds deliberately.

  • Seniors model good behaviour: small changes, quick reviews, kind comments and graceful responses to criticism of their own code.
  • Everyone reviews, including new joiners, so knowledge spreads and nobody becomes a bottleneck.
  • Problems found in review are treated as wins, not as embarrassments.
  • The team periodically discusses what review catches and misses, and adjusts.
  • Blame-free incident reviews ask why review did not catch a bug, as a process question.

Watch for warning signs: rubber-stamp approvals, review as gatekeeping, and people avoiding certain reviewers.

Practice. Run a 30-minute team retrospective on code review with three questions: what helps, what hurts, what to try.

Keep Learning Optional

Review skill grows mainly from practice and reflection, and you will learn more from the following resources than from any single guide: your team's merged pull requests and the comments on them, incident reports that trace a bug back to an approved change, the review guidelines that many large open-source projects publish in their contributor documentation, and reviews written by the engineers you most respect.

Read pull requests in a well-run open-source project you use; you will see how maintainers handle strangers' contributions, decline changes politely and keep standards high. Revisit your own old review comments every few months to see how your judgement has changed.

Practice. Read 20 merged pull requests with discussion in an open-source project and note three review habits you want to adopt.

Code Review Interviews Core

Some interviews give you a pull request or code snippet and ask you to review it, usually in 30 to 60 minutes. They test judgement, priorities and communication more than finding every flaw.

  • Start by clarifying the purpose and context, as you would at work.
  • Do a quick full read, then call out the most serious issues first: correctness, security, data loss.
  • Then cover design, tests and readability, and only briefly mention nits.
  • Phrase findings as you would write them: issue, reason, suggestion.
  • Mention what is good, and what you would approve with follow-ups.

Typical planted bugs include missing authorisation, SQL injection, off-by-one errors, unhandled nulls, race conditions and tests that assert nothing.

Practice. Ask a friend to plant five bugs in a 100-line change and review it in 30 minutes, talking through your priorities aloud.

Projects to build

Build these in order. Each one should end up in a public repository with a short README that explains your decisions.

  1. Personal review guideBeginner

    Write a one-page review guide for yourself: your passes, your key questions and your comment labels. Use it on ten real or open-source pull requests and revise it based on what you missed.

    Reviewing in order · Questions to ask · Comment labels

  2. Split and describe a large changeBeginner

    Take a large feature branch from one of your projects and split it into a stack of small pull requests, each with a full description, clean commits and self-review comments. Ask someone to review the stack and time it.

    Small changes · PR descriptions · Stacked changes · Commit hygiene

  3. Planted-bug review exerciseIntermediate

    With a partner, each write a 150-line change to a small web API with five planted bugs covering authorisation, injection, edge cases, concurrency and a weak test. Swap, review in 45 minutes, then compare findings and comment quality.

    Correctness · Security review · Reviewing tests · Writing clear comments

  4. Automated review pipelineIntermediate

    Set up a repository with a formatter, linter, type checker, tests, static analysis, secret scanning, a CODEOWNERS file, branch protection and a pull request template with a checklist. Document which checks block merging and why.

    Automation · Static analysis · Branch protection · Review checklists

  5. Open-source contribution and reviewAdvanced

    Contribute a fix to an open-source project, responding to maintainers' review. Then review three other contributors' pull requests in the same project with thoughtful, labelled comments, and write a short reflection on what you learned.

    Responding to feedback · Reviewing unfamiliar code · Tone · Mentoring

Interview questions

Try to answer each question out loud before you open the answer.

What do you look for when reviewing a pull request?Junior

I start with the purpose: what problem it solves and whether the approach makes sense. Then the overall design and where logic lives, then the core logic for correctness and edge cases, then the tests, and only then naming and small details. I also think about security, error handling and how it behaves in production. I let automated tools handle formatting so my attention goes to judgement.

How large should a pull request be?Junior

As small as possible while still being a coherent, working step, usually a few hundred lines at most. Small changes get faster, more careful reviews and are easier to roll back. I split refactoring from behaviour changes, put migrations first, and use feature flags or stacked changes for larger work. If I cannot describe a change in one sentence, it is probably two changes.

How do you respond when you disagree with a reviewer's comment?Junior

I first make sure I understand their concern, and assume good intent. If they found a real problem, I fix it. If it is a preference not covered by our conventions, I explain my reasoning once. If we still disagree after a round or two, I suggest a quick call and record the outcome in the thread. If it remains unresolved, we ask the code owner or tech lead and I commit to the decision.

How do you give critical feedback without upsetting the author?Mid

I comment on the code, not the person, and explain the reason and a suggestion: what I noticed, why it matters, and what might fix it. I ask questions where I may lack context, label how serious each comment is, and avoid words like just or obviously. For changes that need many comments, I offer a call instead. I also point out what was done well, specifically.

When do you approve a change that is not perfect?Mid

When it clearly improves the codebase and has no correctness, security or maintainability problems that must be fixed first. Perfection is not the bar; holding out for my preferred style slows the team. I approve with optional suggestions or nits, and track bigger improvements as follow-up tickets. I request changes only for issues I would not want in production.

How do you review a change in an area of code you do not know?Mid

I read the surrounding code and tests to learn the conventions, then focus on what I can judge: clarity, tests, error handling and edge cases. I ask questions openly, which often reveals unclear code. In my approval I say what I did and did not check, so the author can add a domain expert for the parts I could not assess.

What security issues do you check for in every review?Mid

Object-level authorisation, meaning the user can access this particular record, not just that they are logged in. Injection, where input reaches SQL, shell or HTML without parameterisation or encoding. Secrets in code or logs, personal data in logs or URLs, missing input validation and size limits, and requests to user-supplied URLs. For authentication or payments I bring in a security specialist.

How do you judge whether the tests in a pull request are good enough?Mid

I check that every new behaviour and the fixed bug have a test, that tests assert outcomes rather than only running code, and that failure and edge cases are covered. I mentally break the logic and ask which test would fail. I look for flakiness risks such as sleeps or shared state, and for mocking so heavy that the test only checks the mocks. Coverage numbers are a weak signal.

A database migration is in a pull request. What do you check?Senior

Whether it locks a large table, whether it is compatible with old and new code running at the same time during deployment, and whether it can be rolled back. I prefer expand and contract: add new structures, backfill in batches, switch code, then remove old structures later. I check that data migrations are idempotent and tested on realistic volume, and that the deployment order is documented.

Your team's pull requests wait days for review. How would you fix it?Senior

First measure time to first review, change size and review load per person. Typical causes are oversized changes, a few people doing most reviews, and review seen as lower priority than coding. I would agree a turnaround target, encourage smaller changes and stacks, spread reviews with code owners or rotation, automate mechanical checks, and make waiting reviews visible in stand-up. Then I would check the metrics again after a month.

How should a team use AI tools in code review?Mid

As a first pass, like an advanced linter: summarising large diffs and flagging obvious bugs, missing checks and missing tests. They lack business context and can be confidently wrong, so a human reviewer stays accountable. I would agree which comments must be answered, tune out noisy categories, and apply the same standard to AI-generated code: the author must understand and own every line.

What is the most valuable thing code review does, in your view?Senior

Spreading knowledge. Defect detection matters, but tests and static analysis catch many defects more cheaply. Review is unique in making sure more than one person understands each change, keeping the codebase consistent and teaching engineers through real work. That reduces bus-factor risk and improves design over time, which is why I value fast, thoughtful reviews over exhaustive nitpicking.

Tell me about a time a code review caught a serious problem.Mid

A strong answer describes the context, what the change was, what was caught and how, and what changed afterwards. For example: noticing that an export endpoint checked login but not account ownership, explaining the risk with a concrete cross-account request, helping add a test that proved the fix, and then adding authorisation checks to the review checklist so the pattern would be caught again.

How do you review code written by someone more senior than you?Junior

The same way as anyone else's: seniority does not make code correct. I ask questions where I do not understand, which either reveals unclear code or teaches me something. I raise problems directly and politely with reasons. Senior engineers usually welcome thoughtful review, and doing it well is one of the fastest ways to learn the codebase.

Common mistakes

  • Opening huge pull requests that mix refactoring and features; split them into small, focused changes.
  • Requesting review without a description; explain why, what, how to test and the risks.
  • Starting with naming and style comments before checking the design; review from purpose down to details.
  • Approving without running or understanding the change; say what you checked or ask for help.
  • Leaving unlabelled comments so authors cannot tell what blocks merging; mark blocking issues, suggestions and nits.
  • Debating formatting in review; automate it with formatters and linters.
  • Holding out for the code you would have written; approve changes that improve the codebase and track extras as follow-ups.
  • Writing comments that criticise the person or imply they should have known; comment on the code with a reason and suggestion.
  • Letting reviews wait for days; treat review requests as higher priority than starting new work.

Ready-for-interview checklist

  • I can explain why teams review code beyond catching bugs.
  • I can split a large piece of work into small, independently reviewable changes.
  • I can write a pull request description that a reviewer understands before reading code.
  • I can review a change in passes from purpose and design down to details.
  • I can find edge-case, error-handling and concurrency problems in a diff.
  • I can judge whether tests would fail if the code were wrong.
  • I can spot missing object-level authorisation, injection risks and secrets in code.
  • I can review a database migration for locking, compatibility and rollback.
  • I can write comments that state the issue, the reason and a suggestion, labelled by severity.
  • I can resolve a review disagreement without a long comment war.
  • I can set up linters, static analysis, CODEOWNERS and branch protection.
  • I can explain the strengths and limits of AI-assisted review.
  • I can complete a 45-minute code review interview exercise and prioritise findings aloud.

Related roadmaps

FAQ

How long does it take to get good at code review?

You can learn the process and the main things to look for in a few weeks. Judgement, such as knowing what matters most and how to phrase it, grows over months of regular reviewing. Reviewing several changes a week while following this roadmap, most engineers feel confident within two to three months.

Should junior developers review code?

Yes. Juniors learn the codebase fastest by reading changes, and their questions expose unclear code. Teams often require an experienced approver as well for risky areas, but a junior's review is valuable on its own terms.

How long should a code review take?

For a well-sized change of a few hundred lines, often 15 to 45 minutes of focused reading. Attention drops after about an hour, so review in sessions and ask for very large changes to be split. Respond to requests within a few working hours, even if the full review comes later.

Will AI replace human code reviewers?

AI tools already handle part of the first pass well, such as summarising and flagging obvious issues. They do not replace human judgement about business intent, design fit and risk, and they do not spread knowledge across a team, which is one of review's main purposes. Expect to work alongside them.

Do companies test code review in interviews?

Increasingly, yes. Some give you a pull request with planted problems to review; others ask behavioural questions about giving and receiving feedback. Both reward the same skills: prioritising serious issues, explaining them clearly and staying constructive.

Practise while you learn.Solve interview problems in the browser, with hints and a timer.
CodingSQLSystem design
Next Post Previous Post
No Comment
Add Comment
comment url