{"canonical_url":"https://engineer.company/glossary/code-quality/","content_markdown":"# Code quality\n\n## What it is\n\nCode quality is how well source code implements its intended behavior and how readily people can\nunderstand, verify and safely change it. You can see the difference in a small pricing function.\nOne version produces the right value on an ordinary order because it happens to follow the same\nsequence a designer demonstrated. Another expresses the rounding rule in one place, identifies the\ncurrency and handles refunds explicitly. Both may pass a happy-path test. The second gives someone\ninvestigating a disputed invoice a clear place to start.\n\nCorrectness includes boundaries such as invalid input, retries and partially completed work.\nClarity concerns the concepts and choices the next reader can recover from the code. Changeability\nis about how much a later requirement disturbs and whether the team can observe the effects. These\nproperties overlap. A complicated function can be correct today while leaving the next currency\nchange difficult to verify. A short, readable function can still calculate the wrong tax.\n\nCode review is one practice teams use to assess these properties. A quality gate is a rule that\ncan stop work from advancing when selected checks fail. Technical debt describes future costs\ncreated or accepted through a choice. Code quality is the condition of the code itself. Google's\nreview standard asks reviewers to consider whether an individual change improves the health of the\ncodebase as a whole. That gives the broader property an everyday point of application.\n\n## Why it matters\n\nA team experiences code quality most clearly when a requirement changes. Take a service that\ncomputes a quote, creates an invoice and later processes a refund. If each operation independently\ncalculates a discount, changing eligibility means finding and updating every copy. A missing copy\nmay show up only when one customer requests a refund. If the service applies a documented rule at\na shared boundary and each caller supplies its own inputs explicitly, the reviewer can map the\nchange and predict where to test it.\n\nUseful evidence begins with the risk. For money, test the rounding boundary with examples where\nrounding each line comes to a different total from rounding the invoice once. For an operation\nthat can be retried, record whether a second request can trigger a second charge. For a\ncalculation that rarely changes but runs during every checkout, confirm the load and the required\nresponse time before adding caching. Each observation supports a judgment within a particular\nboundary.\n\nThe effect is also social. Engineers rotate, hours of availability change and a reviewer may never\nhave worked with the original author. Clear names, an executable example and a short explanation\nof an unusual constraint allow another person to verify the important detail independently. That\nability matters during incidents and handovers as much as during planned development.\n\n## What it looks like in practice\n\nConsider a hypothetical invoice rule where the business rounds tax on the total for each tax rate.\nOn a two-line invoice the unrounded tax on each line is 0.005 monetary units. Rounding each line\nhalf up to cents gives 0.02 in total. Adding first and rounding once gives 0.01. The example is\ndeliberately small so a reviewer can settle the arithmetic without a spreadsheet. It illustrates a\nchoice that must come from the product and applicable rules for the real invoice.\n\nStart by naming the unit and reading order in the function contract. Keep intermediate values in a\nrepresentation that preserves the required precision. Make the grouping step visible and maintain\none place for rounding at the agreed boundary. The test should use example values with a known\nresult and state why they distinguish the two rules. Choose a second test for mixed tax rates so a\nfuture refactor cannot replace grouping with one aggregate. Give any separate refund policy an\nequally explicit example.\n\nReview the smallest change that repairs the rule. Read the customer-facing amount, the exported\namount and the caller that initiates the refund. Check that historical records retain the amounts\nstored at issuance. Exercise the full invoice path once to verify the callers actually pass the\nright units. A focused test can answer whether an isolated calculation is correct while the\nend-to-end check shows the calculation was hooked up at the right point.\n\nOur note on [selling the last ticket exactly\nonce](/notes/selling-limited-stock-without-overselling/) shows the same evidence-first method for\na different domain. It writes down the inventory invariant, outlines concurrency tests and\nproposes watching the invariant in operation. The formula tells a reviewer what the implementation\nmust preserve across several paths. Put that sort of condition where engineers can read it and\nverify it.\n\n## Where it goes wrong\n\nFirst, a team may mistake a measurable signal for a result. Coverage shows which statements or\nbranches a test executes. It cannot tell whether the expected result encodes the correct rounding\npolicy. A complexity score can point to code worth reading, but replacing one obvious comparison\nwith several obscure helpers can make an incident harder to diagnose. Ask which concrete defect a\nnew measure would help the team catch and read representative examples where it passes and where\nit fails.\n\nSecond, completeness of a cleanup can become the wrong target. A confusing helper used by a single\nlow-risk report might wait. Unclear logic used by every payment or by an irreversible migration\nhas a different cost. Record the trade-off, the observed failure or exposure and when to look\nagain. During a review, separate required correctness changes from optional improvements. A style\ndispute belongs at the level of a shared convention and can often be settled by an automatic\nformatter.\n\nThird, a local improvement can move a problem downstream. Centralizing discounts makes sense where\nseveral callers share one business rule. It becomes misleading if renewal, promotion and refunds\nfollow genuinely different rules but the helper guesses which one applies. Start by describing\nwhich inputs and invariants really match. Share only the stable part and express the differences\nexplicitly. The test suite and the next person's ability to explain the code should both improve.\n\n## Further reading\n\n- [Google's code review\n  standard](https://google.github.io/eng-practices/review/reviewer/standard.html)\n- [What Google reviewers look\n  for](https://google.github.io/eng-practices/review/reviewer/looking-for.html)\n- [Software Engineering at Google on unit\n  testing](https://abseil.io/resources/swe-book/html/ch12.html)\n\n\u003chttps://engineer.company/glossary/code-quality/\u003e\n","date_modified":"2026-11-19T06:00:51Z","description":"Learn how to judge code quality through correctness, clarity and changeability, and use concrete evidence to decide what a team should fix.","formats":{"gemtext":"https://engineer.company/glossary/code-quality/index.gmi","gopher":"https://engineer.company/glossary/code-quality/gophermap","html":"https://engineer.company/glossary/code-quality/","json":"https://engineer.company/glossary/code-quality/index.json","markdown":"https://engineer.company/glossary/code-quality/index.md","pdf":"https://engineer.company/glossary/code-quality/index.pdf"},"kind":"page","language":"en","title":"What is code quality?","url":"https://engineer.company/glossary/code-quality/","version":1}