Measuring What You Have

Before fixing a codebase, you need to know where the problems concentrate. Most developers have an intuition about which files are painful. Intuition is not a baseline. A baseline is a set of numbers you can compare against after making changes, and it must be reproducible by anyone on the team without relying on one person’s memory of which files are bad.

The logistics platform has 338 Java source files. Not all of them are equally expensive to read. The cognitive load concentrates in specific files, specific patterns, and specific dependency relationships. This chapter establishes the tools and techniques for finding them.

Three tools provide the measurement foundation:

SonarQube’s cognitive complexity metric scores individual methods. It counts control flow structures, penalizes nesting depth, and produces a number that correlates with how long a reviewer will spend understanding the method. A score above 15 predicts that a code reviewer will need to re-read the method at least once. A score above 25 predicts that the reviewer will ask questions in the pull request.

ArchUnit tests package dependencies as executable assertions. It runs in your test suite, fails when a dependency rule is violated, and produces a specific failure message identifying the violating class and the dependency that should not exist. It turns architectural decisions into automated tests.

IntelliJ IDEA structural search finds code patterns across the codebase using structural templates rather than text matching. It can find every method with more than three parameters, every class with more than ten fields, or every catch block that swallows an exception. It finds the anti-patterns that text-based grep cannot express.

This chart shows the distribution of cognitive complexity scores across the logistics platform. The bulk of the methods score below 10. But 23 methods score above 25, and those 23 methods account for 68% of all bug fixes in the past six months. The correlation between high cognitive complexity and defect density is not a theory. It is a measurement.