{"canonical_url":"https://engineer.company/glossary/code-review/","content_markdown":"# Code review\n\n## What it is\n\nA code review is the step in which someone other than the author reads a change\nbefore it becomes part of the codebase. Google's guide to its engineering\npractices defines it as code being examined by anyone other than the people who\nwrote it, and the chapter on the subject in _Software Engineering at Google_\nadds that this often happens before the code enters the codebase. The plural,\ncode reviews, is how most teams talk about the practice; the names change with\nthe tool. On GitHub it is a pull request review, at Google it is a precommit\nreview, and in the Linux kernel it happens by email, where a reviewer who is\nsatisfied offers a Reviewed-by tag for the patch.\n\nGoogle's guide lists what a reviewer looks at: design, functionality,\ncomplexity, tests, naming, comments, style and documentation. Behind each word\nis a question. Does the code do what its author meant it to do, and is that good\nfor the people who use it? Could it be simpler? Are there automated tests, and\nare they correct and sensibly designed? Has the documentation that describes it\nbeen updated?\n\nThe mechanics are much the same everywhere. The author sends a diff with a\ndescription, reviewers comment on individual lines, the author answers or\nuploads a new version, and the round repeats until a reviewer accepts the\nchange. At Google that acceptance is called LGTM, short for _looks good to me_,\nand the book describes it as a permissions bit: only one LGTM is required by\ndefault, and together with approval from a code owner and a readability check it\nallows the change to be committed. GitHub ends each review with one of three\ndecisions. Comment gives feedback that neither approves nor asks for changes,\nApprove says the change can be merged as it stands, and Request changes marks\npoints the author has to deal with first. Anyone who can read the repository can\nreview and comment, and its administrators can make approval a condition of\nmerging. Google's guide calls each change a CL, which is why one of its pages is\ntitled Small CLs.\n\n## Why it matters\n\nThe book lists six benefits of a well-run review. It checks that the code is\ncorrect, makes sure other engineers can understand the change, enforces\nconsistency across the codebase, promotes team ownership, spreads knowledge and\nleaves a historical record. Correctness is the obvious one, and the authors cite\na study at IBM, published in 1986, which found that defects discovered earlier\ntook less time to fix. The book adds the condition that matters: the time\ninvested in review paid off only while the process stayed lightweight. Static\nanalysis and automated tests now carry much of the correctness work, which the\nbook says has lessened the need to rely on people for it.\n\nComprehension is the benefit no tool replaces. However good an engineer is, they\ncannot read their own work as a stranger would, and a reviewer can; review is\noften the first time anyone but the author checks that a change makes sense.\nThat matters because code is read far more often than it is written. The\ncultural benefits are quieter. Review reminds an engineer that the code is not\ntheirs but part of a shared enterprise, it lets experts pass on what they know\nabout an area, and because every change keeps its review, anyone can later find\nout when a pattern arrived and read the review that brought it in.\n\nReview also costs time, and slow review costs more. Google's guide on speed says\nthat when reviews are slow, the whole team moves more slowly, developers begin\nto resent the process, and code health suffers, because there is pressure to let\nweaker changes through and cleanups get discouraged. Most complaints that a\nreviewer is too strict, it adds, go away when the same reviewer simply answers\nfaster. Its standard for approving is pragmatic: once a change clearly leaves\nthe code health of the system better than it was, reviewers should lean towards\napproving it, even if it is not perfect. The guide calls this the senior\nprinciple among its rules and puts the reason in one line: \"there is no such\nthing as 'perfect' code—there is only better code\".\n\n## What it looks like in practice\n\nTake a shop whose prices are stored in whole pence. An author adds a spring\ncampaign and sends this change for review:\n\n```diff\n--- a/shop/pricing.py\n+++ b/shop/pricing.py\n@@ -8,2 +8,4 @@ def order_total(basket):\n     subtotal = sum(line.price * line.quantity for line in basket.lines)\n+    if basket.voucher == \"SPRING\":\n+        subtotal = subtotal * 0.9\n     return subtotal + shipping_for(basket)\n```\n\nThe reviewer leaves four comments:\n\n```text\nshop/pricing.py, line 9\n  The other vouchers and their rates live in VOUCHERS in\n  shop/vouchers.py. Could SPRING go there too? Then the next\n  campaign is a change to data, not to this function.\n\nshop/pricing.py, line 10\n  Prices are whole pence everywhere else in this module, and\n  multiplying by 0.9 can leave a fraction of a penny. The other\n  discounts go through round_money() in shop/money.py.\n\nshop/pricing.py, line 11\n  Nit: shipping is left out of the discount. If that is on\n  purpose, a short comment saying so would help the next reader.\n\nGeneral\n  There is no test with a voucher on the basket. Could you add\n  one for SPRING and one showing that an unknown code changes\n  nothing?\n```\n\nEach comment is about the code rather than the person, and each says why. The\nfirst two and the last carry no label, so they are expected to be dealt with;\nthe third starts with Nit:, which Google's guide uses for a small point the\nauthor ought to fix but that changes little. The guide's other labels are\nOptional, or Consider, for a good idea that is not required, and FYI, for a\nthought the author is not expected to act on in this change. Without labels, it\nwarns, authors may read every comment as mandatory. On GitHub this round ends\nwith Request changes. The author moves SPRING into the table, routes the\ndiscount through the rounding helper, adds the comment and both tests, and asks\nfor another look; the second round ends with Approve, or at Google with LGTM.\nThe guide asks reviewers to answer a review request within one business day at\nmost, and not to break off a focused task to do it but to wait for a natural\nbreak.\n\nNone of the comments is about formatting, import order or whether the tests\npass, because a machine should have said that before the reviewer opened the\ndiff. The book describes presubmits that run when a change is first sent for\nreview and can reject it before anyone reads it; the kernel asks authors to run\nits style checker, `scripts/checkpatch.pl`, before they submit. The\n[guard engine built for a repository](/portfolio/built-a-268-check-guard-engine-for-the-repo/),\nfrom 2025, takes that idea a long way: 268 registered commit checks, 277 lint\nrules and 15 custom ESLint rules, plus 146 tests of the guards themselves. The\nguards check things such as whether a migration can be rolled back and whether a\ntranslation key exists in both locales, and any commit marked as a fix has to\ncarry a test that fails without it. The checks encoded mechanical rules, so reviewers could spend more time on design. It also states the cost:\ncommitting is slow, and a badly written guard is infuriating to work around.\n\n## Where it goes wrong\n\n**The change is too big to read.** Google's guide calls 100 lines usually a\nreasonable size for a change and 1,000 lines usually too large, while leaving\nthe call to the reviewer, and notes that 200 lines in one file might be fine\nwhen the same 200 lines spread across 50 files would not be. Small changes are\nreviewed more quickly and more thoroughly and are less likely to introduce\nbugs; the book adds that reviewers can rightly reject a change as too large for\na single review. Split the work: stack small changes on top of each other, send\ngroups of files to different reviewers, keep refactorings apart from feature\nchanges and bug fixes, and keep each change's tests in the same change.\n\n**The review sits for days.** Every day a change waits delays the work built on\nit, and a reviewer who answers every few days with major requests makes the\nprocess feel harsher than it is. Answer within one business day; the book's\nexpectation is feedback within 24 working hours, and if the full review has to\nwait, a reviewer should say they have seen the change. Send all the comments at\nonce rather than piecemeal, since few things annoy an author more than a new\nround of unrelated feedback after the last one was addressed.\n\n**Taste is presented as a requirement.** A reviewer who prefers another loop or\nanother name and blocks the change over it trains authors to stop improving the\ncode. Google's guide sets the order: facts and data count for more than opinion\nor personal taste, on matters of style the style guide has the last word, and\nwhen several approaches are equally sound, the author chooses. Label a\npreference as Nit or Optional, so that the author can tell it apart from a\nrequirement.\n\n**The comment is about the person.** The guide's own example of a bad comment\nasks why the author used threads when there is obviously no benefit from\nconcurrency; the good version says the concurrency model adds complexity with\nno performance benefit the reviewer can see, so the code should be\nsingle-threaded. Comment on the code, never on the developer, and explain the\nreasoning behind the request.\n\n**People check what a machine could.** Reviewers who spend their attention on\nspacing and import order miss the design question that only a person can\nanswer. Move every rule that can be written down into a linter, a formatter or\na presubmit check, and leave the reviewer the judgement calls.\n\n**The answer stays in the review tool.** A reviewer asks what a block of code is\nfor, the author explains in the thread, the reviewer approves, and the next\nperson to read the code never sees the explanation. Google's guide says such a\nquestion should usually lead to the code being rewritten more clearly, or at\nleast to a comment in the code. The kernel makes the same point to authors: when\na reviewer's question changes no code, the answer should, as a rule, end up in a\ncomment or in the changelog.\n\n## Further reading\n\n- [Introduction](https://google.github.io/eng-practices/review/)\n  — the opening page of Google's code review guide: what reviewers look for,\n  how to pick reviewers and when pair programming counts as review.\n- [The Standard of Code Review](https://google.github.io/eng-practices/review/reviewer/standard.html)\n  — the senior principle, mentoring through review, and how to resolve\n  conflicts between author and reviewer.\n- [Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)\n  — why small changes get better reviews, how big is too big, and four ways to\n  split a change.\n- [Code Review](https://abseil.io/resources/swe-book/html/ch09.html)\n  — Tom Manshreck and Caitlin Sadowski's chapter of _Software Engineering at\n  Google_: the benefits of review, LGTM and ownership, and best practices.\n- [Pull request reviews](https://docs.github.com/en/pull-requests/reference/pull-request-reviews)\n  — GitHub's reference for reviewing, approving and requesting changes, and\n  for requiring approvals before a merge.\n- [Submitting patches: the essential guide to getting your code into the kernel](https://docs.kernel.org/process/submitting-patches.html)\n  — how the Linux kernel reviews by email, what a Reviewed-by tag states, and\n  how authors should answer reviewers.\n\n\u003chttps://engineer.company/glossary/code-review/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What a code review checks, a worked review of a small pricing change with labelled comments, and the habits that make reviews slow or personal.","formats":{"gemtext":"https://engineer.company/glossary/code-review/index.gmi","gopher":"https://engineer.company/glossary/code-review/gophermap","html":"https://engineer.company/glossary/code-review/","json":"https://engineer.company/glossary/code-review/index.json","markdown":"https://engineer.company/glossary/code-review/index.md","pdf":"https://engineer.company/glossary/code-review/index.pdf"},"kind":"page","language":"en","title":"What is a code review?","url":"https://engineer.company/glossary/code-review/","version":1}