Code Quality

Code quality is the degree to which source code is easy to read, understand, change and trust. It is the finest-grained level of maintainability: architecture decides where a change lands, and code quality decides how expensive that landing is. In practice it has five attributes: readable, with names and small functions that reveal intent; simple, with no more complexity than the problem needs; correct, provably, through types and strong tests; consistent with the rest of the codebase; and secure against common weaknesses. Each has an indicator, such as review time, cognitive complexity, mutation score or SAST findings. At ShopNow, the most complex checkout methods had five times the defect density of the rest.

A code smell is a surface symptom in code that suggests a deeper design problem, a term popularised by Martin Fowler. It is not a bug, and the code may work perfectly, but it signals that change will be harder or riskier than it should be. Common examples are long methods, large classes, long parameter lists, duplicated business rules, primitive obsession, feature envy, where a method uses another class's data more than its own, and boolean flag parameters. Each smell suggests a refactoring: Extract Method, Introduce Parameter Object, replace primitives with value objects such as Money, or replace conditionals with polymorphism or pattern matching. Static analysis flags many smells; reviewers judge which matter.

Cyclomatic complexity counts the number of independent paths through a method, essentially one plus the number of decision points, so it estimates how many test cases are needed to cover it. Cognitive complexity, defined by SonarSource, measures how hard the code is for a human to understand: it penalises nesting more heavily, counts breaks in linear flow such as loops, jumps and recursion, and ignores structures that read easily, such as a flat switch. A ten-case switch has high cyclomatic but low cognitive complexity, while three nested ifs inside a loop score the opposite. For maintainability, cognitive complexity is the better gate; ShopNow limits new methods to 15.

Coverage only shows that code was executed by a test, not that the test would fail if the code were wrong. A test can call a method and assert nothing, or assert only that the result is not null, and still produce 90% line coverage. Mutation testing exposes this: a tool such as PIT makes small changes to the code, for example turning greater-than into greater-or-equal, and checks whether any test fails. At ShopNow the promotions module had 88% line coverage but only a 52% mutation score, because many tests had no meaningful assertions. Combine coverage on new code with mutation scores and property-based tests on domain modules.

Code review should focus on what machines cannot judge: design, naming, module boundaries, failure handling and whether tests verify behaviour. Formatting, style and common bug patterns should already be enforced by Spotless, Error Prone, NullAway and Sonar, so reviewers do not spend attention on them. Good review questions are whether the name says what the code does, whether the change sits in the right module, what happens on failure, whether there is a test for the behaviour rather than just the lines, whether anything clever could be plain, and whether a public contract changes. At ShopNow, automating style cut style comments by 70% and median review time from 26 to 9 hours.

Sealed types let you declare a closed set of subtypes, for example a sealed Promotion interface permitting only PercentageOff, FlatOff, BuyXGetY and FreeShipping. Combined with pattern matching in a switch expression, the compiler checks exhaustiveness: the switch needs no default branch, and if someone adds a new promotion type, every switch that does not handle it fails to compile. That turns a class of runtime bugs, the forgotten case, into compile errors and makes the domain model explicit in the code. Records as the permitted subtypes add immutable, boilerplate-free data. At ShopNow, adding a promotion type now takes one class and one switch case, and the compiler finds the switch.

Apply the gates to new and changed code only, an approach often called clean as you code. If gates measured the whole legacy codebase, every build would fail and teams would either disable the checks or stop working. Instead, configure SonarQube's new-code period so that only lines added or modified in the pull request must meet complexity, duplication, coverage and security rules, while the existing debt is tracked separately. Over time, the code people actually touch improves, which is where improvement pays off. Pair it with targeted refactoring of hotspots, the files that change most and have the most defects, rather than an unfocused clean-up of rarely changed code.

Duplication is acceptable when code looks similar but represents different concepts that will change for different reasons. Merging them creates the wrong abstraction: a shared method full of flags and special cases that couples two parts of the system, which is worse than the duplication it removed. For example, a customer return window and a seller payout hold period may share the same date arithmetic today, yet they belong to different teams and change for different reasons. Copy-pasted business rules, by contrast, must be consolidated, because a fix applied to one copy will be missed in the other. A useful rule of thumb is to wait for the third occurrence before abstracting.

Make quality the default of the platform rather than the effort of each team. Put the gates in shared CI templates so all teams get the same formatter, Error Prone and NullAway rules and Sonar new-code thresholds automatically. Start every new service from a golden-path template that is already clean, and provide shared libraries for value types such as Money and identifiers. Publish per-team metrics, such as gate pass rate, median review time and mutation score on domain modules, and use them comparatively to find where help is needed, not to punish. Back it with shared examples, review guidelines and communities of practice, so standards spread through people as well as tools.

Refactor in small, behaviour-preserving steps protected by tests. If the code has no tests, first write characterisation tests that capture its current behaviour, even where that behaviour looks wrong, so any accidental change is detected. Then apply one refactoring per pull request, such as Extract Method, Introduce Parameter Object, replacing primitives with value objects or replacing conditionals with pattern matching, keeping each change easy to review and revert. When behaviour must change as well, do it separately and behind a feature flag. ShopNow refactored its 120-line applyPromotions method in six small PRs, reducing cognitive complexity from 48 to 9 with zero defects the following year.