Software Design X-Rays

Adam Tornhill · epub · 2018-03 source ↗ Reader 🖥️

practical · mixed — A practical, technique-driven book (how to mine version control and act on the results) built on a theoretical spine borrowed from cognitive and social psychology (schemas, the forgetting curve, diffusion of responsibility, process loss), and carried throughout by real open-source and commercial case studies (ASP.NET Core MVC, Linux, Android, Scala, nopCommerce, Spinnaker) that function as evidence, not decoration.

Structure

Key terms

• Interest rate (on technical debt)
  A property of code that can only be defined with a time dimension: how often you actually have to read/modify a piece of code. Bad code you never touch isn't debt because you never pay interest on it.
• Hotspot
  Complicated code (approximated, language-neutrally, by lines of code) that also changes at a high frequency — the operational definition of 'technical debt that matters.'
• Change coupling (the author explicitly disowns 'temporal coupling' for this) Behavioral Code Analysis
  Two or more files/functions that change together over time in version-control history, detected purely from co-occurrence in commits/logical change sets, independent of any static code dependency.
• Code age / the three generations of code
  Code should be classed as recent (actively worked, fresh mental model), old (stable, safe to treat as a black box), or mid-aged (the expensive middle, where memory has decayed below the Ebbinghaus curve but the code must still be revisited) — a reframing of Dan North's 'short software half-life.'
• Fractal value (developer diffusion / fragmentation)
  A normalized 0.0-1.0 measure of how diffused a module's authorship is across contributors (0 = single author, closer to 1 = many roughly-equal minor contributors), used as a proxy for coordination need and defect risk.
• Diffusion of responsibility (applied to code)
  The social-psychology finding (borrowed, with the bystander-effect as its classic illustration) that individual accountability for a shared resource erodes as the number of people sharing it grows — applied here to explain why hotspots with many minor contributors stay bad for years despite being easy to fix.
• Splinter pattern
  An iterative refactoring that extracts a hotspot's responsibilities into new, imperfect-but-separable modules behind a facade that preserves the original API — explicitly not a quality improvement in itself, but a structural precondition that lets multiple people work on a hotspot in parallel without freezing feature work.
• Knowledge map / knowledge-loss simulation
  A visualization of each file's main historical contributor (from authorship share), and a what-if analysis that removes a (soon-to-leave) contributor's commits to show which modules would lose their de facto expert — turning offboarding risk into something measurable before the fact.
• Technical sprawl / conservation of familiarity
  The erosion of an organization's working knowledge of its own system (Lehman's law of 'conservation of familiarity') caused by unrestrained per-service technology choice in microservices — measured via a fractal-value-style index over programming languages per service.

Propositions

• explicitdevelopedTechnical debt is not identical with bad or ugly code; code only becomes debt once you have to pay interest on it by repeatedly reading or modifying it, so interest rate is a function of time and requires a time dimension on the code to be measured at all.conf: high
  extendsTechnical Debt Quadrant · p2 — Tornhill supplies a measurable, time-based operational test for 'is this actually debt' (change frequency x complexity, mined from version control), complementing Fowler's qualitative reckless/prudent taxonomy of what counts as debt.
  extends ←Code Red: The Business Impact of Code Quality -- A Quantitative Study of 39 Proprietary Production Codebases · p7 — Both papers share the TD-interest framing (debt is the recurring interest payment, not the remediation cost); this paper supplies the quantified interest rate (124% / 9x) that the book's hotspot/interest-rate metaphor leaves qualitative.
• explicitThe structure of the development organization is a stronger predictor of software defects than any code-level metric, including complexity and test coverage.conf: high
• explicitParallel development increases defect risk even within a strong peer-review culture — shown empirically on the Linux kernel, where modules with the most parallel work had more security bugs despite open-source review norms.conf: high
• explicitProgrammers understand code through mental schemas built over time; heavy parallel/congested development invalidates those schemas faster than any individual can rebuild them, and this — not code quality per se — is the actual mechanism behind 'this code is hard to understand' complaints that get misdiagnosed as a purely technical problem.conf: high
  supports11) AI-spesial med Vilde Opsal og Anders Sveen · p4 — Supplies the cognitive mechanism — code legibility as externalized support for a reader's mental schema — behind why clear information architecture should matter to both human and agent 'readers' of a codebase.
• explicitVersion control is a behavioral log of how developers have actually interacted with the code, not merely a backup system — and it is the only available source for the time dimension and social data needed to prioritize technical debt and detect organizational risk.conf: high
• explicitA hotspot — complicated code (lines of code as a simple, language-neutral complexity proxy) that also changes at high frequency — is the correct unit for prioritizing technical debt, because low-quality code that is rarely touched is not actually costly.conf: high
  extendsThe Economic Benefit of Refactoring · p9 — The hotspot/interest-rate metric — a measured proxy for where real maintenance cost concentrates, mined from version-control history rather than inspected from code alone — is the direct conceptual ancestor of using a measured proxy like agent token cost as an 'AI-friendliness' signal.
• explicitComplexity-trend analysis — an indentation-based, language-neutral complexity metric tracked across a file's historic revisions — distinguishes files that merely grew in size from files that grew in complexity, revealing whether a hotspot is getting structurally worse over time.conf: high
• explicitChange coupling (files or functions that change together over time) is invisible in the code itself and detectable only by mining version-control history; the most valuable findings are 'surprising' couplings with no visible static dependency, because those point to hidden dependencies or missing abstractions.conf: high
• explicit'There's no such thing as just test code': unit tests that change together for reasons unrelated to the application code they test reveal missing test-design abstractions (shared test data, custom assertions), and poorly designed test suites become a disproportionate source of hotspots and change coupling.conf: high
• explicitThe splinter pattern — extracting a hotspot's responsibilities into new modules behind a facade that preserves the original API, delivered in short iterations rather than on a long-lived branch — is how you refactor a hotspot that is simultaneously under heavy, unavoidable parallel feature development.conf: high
• explicitCode-quality problems are typically introduced at the moment a file or class is first created, not accumulated gradually afterward — so the pull-request/initial-design moment, not later cleanup, is the real intervention point.conf: medium
• explicitCode should be either very recent (still within active working memory) or old and stable (safe to treat as a black box); code of intermediate age is the most expensive category because memory of it has decayed (the Ebbinghaus forgetting curve) while it still must be revisited — a reframing of Dan North's claim that software should have a short half-life.conf: high
• explicitThe risk of a new defect in a module declines roughly a third per year of the module's age, because time both exposes it to more use cases and lets it get 'patched into correctness' — meaning complaints about old, untouched code are often organizational folklore rather than evidence of a live problem.conf: high
• explicitHotspot and complexity-trend analysis scale from individual files up to whole architectural subsystems by aggregating the same underlying change-frequency/complexity data at the logical-component level — the level at which nontechnical managers can act on the results.conf: high
• explicitComplexity trends function as an organizational whistleblower against the normalization of deviance (gradually accepting code that keeps getting a little worse), because they give an unbiased historical reference point that day-to-day familiarity erodes.conf: high
• explicitModular boundaries aligned with problem-domain concepts, rather than solution-domain/technical layers, give each team natural end-to-end ownership and let architecture scale with the organization; technically oriented architectures instead force either universal cross-team coordination or single-team ownership bottlenecks — this is the operational content the book draws out of Conway's Law.conf: high
• explicitMeasured empirically across real layered codebases, roughly 30-70% of commits cut across multiple architectural layers, showing that a layered architecture typically separates the wrong concern, since the real unit of change is a user-facing feature, not a technical layer.conf: high
• explicitDeveloper fragmentation — many minor contributors to one module, measured via a normalized fractal value — correlates with higher defect rates independent of a module's technical quality; a module with one clear primary author plus open contribution carries lower risk than one with many roughly-equal minor contributors.conf: high
• explicitCode ownership is a structural countermeasure to diffusion of responsibility, not an exclusionary claim on code ('stay away'); it should pair narrow operational ownership (who writes most of a module) with deliberately broad knowledge boundaries (who understands it, widened through reviews, rotations, and walkthroughs).conf: high
• explicitChange-coupling analysis can suggest domain-driven-design bounded contexts directly from how the code actually evolves — sometimes revealing a bounded context the documented or intended architecture fails to capture.conf: medium
• explicitMicroservice architectures reproduce the coordination problems of layered monoliths at a different granularity: implicit change coupling across repository boundaries ('microservices shotgun surgery'), monolithic UIs that re-centralize what the backend split up, and technical sprawl from divergent per-service languages/frameworks that erodes the 'conservation of familiarity' Lehman's laws require.conf: high
• explicitKnowledge maps (visualizing each file's main contributor from authorship data) and knowledge-loss simulations (virtually removing a departing contributor's commits) turn offboarding risk from guesswork into a measurable, actionable simulation available before the departure happens.conf: high
• explicitSocial/organizational behavioral analyses are far more bias-prone than technical ones (hotspots, complexity trends): misattributed merge authorship, history-losing repository splits, squash commits, and unrecorded pair/mob programming all corrupt the social signal — when data quality is in doubt, the technical analyses should be trusted over the social ones.conf: high
• explicitThere is a direct economic argument for readable code distinct from aesthetics or professional pride: because developers spend most of their time understanding existing code before changing it, optimizing for readability is an organizational efficiency choice; relatedly, a hotspot's history should be read through the fundamental attribution error — as evidence of past situational pressure on the developers who wrote it, not of their incompetence — which argues for forward-looking triage over retrospective blame.conf: high
• implicitEvery social metric the book introduces (code ownership, fractal value, knowledge maps, knowledge-loss simulation) is built from version-control authorship as a proxy for who understands the code — the method tacitly assumes that writing and understanding stay coupled in one human contributor who can 'leave' or need 'onboarding,' an assumption the book never states as an assumption because it had no other kind of contributor to consider in 2018.conf: medium

Arguments

Narratives

• An organization runs a quantifying tool on its 15-year-old codebase and is told it carries '4,000 years' of technical debt, leaving no way to decide where to start.
  → Shows that a technical-debt measure with no time dimension is operationally useless for prioritization, motivating the hotspot concept.
• A project with its schedule compressed from one year to three months by quadrupling headcount ends up with high defect rates and low morale, even though the author, reviewing the code directly, finds it 'by no means particularly hard to understand.'
  → Demonstrates that organizational congestion, not code quality, was the real driver of the team's struggles — grounding the chapter's mental-schema argument.
• A hotspot analysis of Microsoft's ASP.NET Core MVC identifies a 2,500-line unit test, ControllerActionInvokerTest.cs, as the top hotspot, and a complexity-trend analysis confirms its complexity has grown sharply without a corresponding increase in comments.
  → Shows the hotspot + complexity-trend combination jointly locating and confirming a real maintenance problem in a real, inspectable codebase.
• Android's ActivityManagerService.java, a 20,000-line hotspot with only 33 lines of unit-test coverage, is refactored using the splinter pattern — extracting cohesive behaviors into new classes behind a delegating facade, in fast, incremental steps rather than on a branch.
  → Makes the splinter pattern concrete and shows it is deliberately designed for code too large and too contested to refactor in one sweep.
• A consultant is hired to review a flawed, much-complained-about database framework, only to find via code-age analysis that the code hasn't been touched in a year and isn't actually defect-dense — the complaints were folklore, not data.
  → Illustrates that old, stable code is often mistakenly targeted for rewrite based on reputation rather than evidence, supporting the 'your best bug fix is time' proposition.
• Two long-time Scala contributors, Paul Phillips and Simon Ochsenreither, publicly announce they are leaving; a knowledge-loss simulation on the Scala codebase shows the interactive REPL package in particular loses its main developer.
  → A real-world case study of knowledge-loss simulation in action, including an example of classifying the resulting risk as low (REPL, widely understood in general) versus high (Scala-specific type-system internals).
• In a medical-domain codebase, a shared 'Patient' class accumulates getters and setters for unrelated use cases — including a UI editor's fields and an entirely separate subsystem's network-transfer status — forcing every consumer to depend on properties irrelevant to their context.
  → Motivates bounded contexts as a remedy for a shared global model, and sets up change-coupling analysis as a way to discover where such contexts actually are.

Questions addressed

• ✅ Given a large codebase with far more subpar code than time to fix it, how do you decide where to start?
  Hotspots: rank code by change frequency x complexity, both mined from version control.
• ✅ Does the current architecture actually support the way the system evolves, or does it fight the way people work?
  Change-coupling analysis across files, layers, components, and services reveals where the architecture's stated boundaries diverge from the real, evolving ones.
• ✅ Where are the hidden interteam coordination bottlenecks in a large organization?
  Developer-fragmentation (fractal value) analysis combined with Conway's-Law-aligned architecture.
• ✅ How do you know, before someone leaves, what knowledge the organization would lose?
  Knowledge maps plus knowledge-loss simulation on version-control authorship data.
• ⭕ What happens to all of these author-based social metrics once a large and growing share of commits comes from an AI agent rather than a human who can 'understand,' 'leave,' or need 'onboarding'?

Gaps

• incompleteEvery social metric in the book (ownership, fractal value, knowledge maps, knowledge-loss simulation) is built entirely on human-author version-control identity as a proxy for who understands the code. The book has no answer for a world where a large share of commits are authored by AI agents under human supervision/review, which breaks the implicit equation of 'who wrote it' with 'who understands it' exactly where agent-authored commits are frequent and numerous. For AI-era teams, this suggests the next generation of these metrics may need 'who understands this code' decoupled from 'who/what wrote this code' — reviewer/approver identity or demonstrated modification history might be better proxies than raw commit authorship once agents are prolific contributors.
  Read next: Look for post-2023 work that re-derives social code metrics (ownership, knowledge mapping, bus-factor-style analyses) using reviewer/approver signals rather than commit authorship, and for any extension of Tornhill/CodeScene's own Code Health work into the social half of this book.
• incompleteThe hotspot/interest-rate framework (technical half of the book) has a documented modern descendant — CodeScene's Code Health metric, shown elsewhere in this corpus (extract-codescene-refactoring-at-scale-with-agents) to predict agentic refactoring performance on at least one case study. But that validation covers only the technical metric; it remains untested in this corpus whether the book's social/organizational metrics (ownership, developer fragmentation, knowledge maps) predict anything about agent-era risk at all, since agents don't suffer diffusion of responsibility or the forgetting curve the way human teams do.
  Read next: Look for empirical work correlating team-level social code metrics (fractal value, ownership diffusion) with outcomes in codebases where AI agents do a large share of the implementation work.
• incompleteThe book's code-age argument depends specifically on human memory decay (the Ebbinghaus forgetting curve) to explain why mid-aged code is the most expensive category to maintain. If AI agents — which have no forgetting curve within a session but also no persistent memory across sessions without deliberate context engineering — become primary code modifiers, it is unclear whether 'mid-aged code' remains the most expensive category, or whether a different, session-reset-driven risk curve applies instead.
  Read next: Look for work on how code-age-based maintenance risk should be modeled when the dominant modifier re-derives understanding from scratch each session regardless of the code's calendar age.
• incompleteThe book repeatedly asserts that layered/technically-oriented architectures are worth their coordination cost 'for small teams' but never quantifies the threshold at which that trade-off flips — the 'Optimize for the Ordinary' aside gestures at the cost without giving any decision procedure for when an organization should migrate from layers to package-by-feature/component or microservices.
  Read next: Look for later work (e.g., Team Topologies, or empirical studies of architecture migrations) that attempts to quantify team-size or coordination-cost thresholds for abandoning layered architectures.

Closes gaps elsewhere

• Bliki: Mythical Man Month · g2 — Tornhill resolves the tension Fowler leaves unexamined between chief-architect-style conceptual integrity and collective code ownership by reframing ownership as a countermeasure to social-psychology's diffusion of responsibility rather than exclusion: pair narrow operational ownership (who writes most of a module) with deliberately broad knowledge boundaries (who understands it, via reviews/rotations/walkthroughs), backed by empirical findings that clear primary ownership lowers defect rates while broad knowledge boundaries ease interteam coordination.

Related documents

• 11) AI-spesial med Vilde Opsal og Anders Sveen
• The Economic Benefit of Refactoring
• Technical Debt Quadrant
• The Hard-Stop Rule: From 3 HCM Monoliths to 120 Domain Microservices
  Modularity & Coupling Sociotechnical Architecture Technical Debt
• Code Red: The Business Impact of Code Quality -- A Quantitative Study of 39 Proprietary Production Codebases
  AI-Friendly Code (Code Health for Agents) Behavioral Code Analysis Technical Debt
• Architecture Modernization: Aligning software, strategy, and structure • Nick Tune • CodeCrafts 2024
  Behavioral Code Analysis Modularity & Coupling Sociotechnical Architecture
• Agents don't know what good looks like. And that's exactly the problem.
  Modularity & Coupling Sociotechnical Architecture
• AI coding creates two kinds of debt. You're only measuring one
  Mental Models & Understanding Technical Debt
• The "funhouse mirror": How AI reflects the hidden truths of your software pipeline
  Modularity & Coupling Technical Debt
• Case Study: Refactoring at Scale with Agents
  Behavioral Code Analysis Technical Debt