Measuring Software Architecture
In short: This series takes ten ideas from software architecture research and tests them on real code. Most parts measure one idea on open-source projects and report the numbers. Some ideas held up. Picked from 18 months of history, 325 of 1,809 files caught 446 of 701 later likely bug-fix touches. Some did not. Once size and activity were in the model, knowing who owns a file did not help predict later fixes in any of five projects.
Each part explains where an idea comes from, then checks it against data. This page lists the ten parts and what each one found.
Four kinds of evidence
Each part reads one kind of evidence about a system. Parts 2 to 4 read the code's structure: which files import which. Parts 5 to 7 read version history: which files change, and how often. Parts 8 and 9 read the people behind the commits. Part 10 reads runtime traces, the record of real requests.
Part 1 covers the practice the rest feed into. A fitness function is a check with a threshold. It runs on every change and fails the build when one architectural quality slips.
The ten parts
-
Part 1 · Practice
Fitness Functions: Telling If Your Architecture Still Works
A fitness function is a check with a threshold that fails the build when one architectural quality slips. The same loop covers a layering rule, a performance budget and a firmware size limit.
-
Part 2 · Code structure
The Modularity Maturity Index
The index scores a codebase from 0 to 10 on modularity, hierarchy and pattern consistency. On six real projects the three pillars disagreed.
-
Part 3 · Code structure
Propagation Cost: The Number That Measured Mozilla's Rewrite
Propagation cost is the share of a codebase that a change to one file can reach. eslint and webpack are about the same size and land a factor of fourteen apart.
-
Part 4 · Code structure
Decoupling Level: How Replaceable Is Your Codebase?
Decoupling level measures how much of a system lives in small modules that nothing else depends on. My approximation puts Moment at 75.72 percent, eslint at 63.91 and webpack at 4.06.
-
Part 5 · Version history
Architecture Debt with an Actual Interest Rate
An architecture debt is a group of files whose flawed connections keep costing bug fixes. In webpack and vite, the files inside the five most expensive debts took four to six times their share of bug-fix lines.
-
Part 6 · Version history
Change Coupling: The Dependency Graph Only Git Can See
Across five projects, 523 file pairs co-changed strongly. 342 of them, 65 percent, have no import between them.
-
Part 7 · Version history
Code Hotspots: Where Complexity and Churn Meet
A hotspot is a file that is both large and frequently changed. 325 of 1,809 files caught 446 of 701 later likely bug-fix touches, 3.54 times their share of files.
-
Part 8 · People
Conway's Law, Measured: Git Can Only See Half
Three of five repositories showed more contributor-module structure than their activity predicts. Two did not. Nothing in a repository says who reports to whom.
-
Part 9 · People
Code Ownership, Measured: The Five-Percent Problem
I asked whether a file with one dominant contributor needs fewer fixes later, once size and activity are in the model. In all five projects, it did not help.
-
Part 10 · Runtime
Runtime Traces, Measured: A Map of What Gets Used
I built one system's service map from recorded traces and from its code. Where both could see, they agreed. What traces added was use: 11 of the 38 services never received a request.
Where to start
For one number to watch in CI, start with Decoupling Level. In its paper, the metric's coefficient of variation between ordinary releases was 2 percent, against 12 for propagation cost.
If all you have is a git history, start with code hotspots. A hotspot needs only two inputs: how large a file is and how often it changes.
To see what an import graph misses, read change coupling. And before building a trace pipeline for architecture work, read the runtime traces part. For structure, reading the code was cheaper.