The engineering offsite opens with a map of the codebase. A treemap: every module a rectangle, sized by lines of code. The biggest blocks dominate the screen, and the discussion immediately organizes around them. The billing monolith is huge. The legacy importer is huge. Two engineers spend the session defending the size of blocks they own.
A quieter engineer reruns the map that evening with one change: the rectangles are sized by change frequency, how often each module was touched in the last six months. The picture inverts. The billing monolith is a stable mass, touched monthly. The rectangle now screaming for attention is a modest checkout module, small, nondescript, modified more than anything else in the system, week after week.
The first map showed where the mass is. The second showed where the team lives. Those are different questions, and only one of them is about work.
Size is a claim about what matters
Every map with sized elements makes an implicit argument: the big things are the important things. Choose the size variable carelessly and the map argues a position nobody defended.
Lines of code argues that mass is importance. But mass is mostly history. It tells you where the system has been, rewards code that accreted, and visually punishes the refactoring that deleted a hundred thousand lines, which is the opposite of the incentive a map should carry. Estimated effort argues that plans are importance, but estimates are optimism with a number, and finished work dominates the map forever while current work barely registers.
Change frequency argues something verifiable: this is where attention is going. Not where it should go, where it does go. Churn is the repository's honesty signal, because attention cannot be claimed in a map, only observed in commits. A module touched every week is a module the organization is paying for weekly, whether anyone budgeted for it or not.
There is a market-facing version of this argument in Maps That Tell the Speed of Change: roadmaps show position, but markets compete on velocity, and snapshots of position mislead. The codebase version is the same lesson turned inward. A map of mass shows position. A map of churn shows velocity, and velocity is where the truth about a system's health lives.
What does churn actually measure?
Three different stories wear the same measurement, and reading them apart is the skill.
Load. High churn because the module carries live product work: features, experiments, integration. This is healthy attention, the sound of the system being used. The map's job here is visibility: the team should know where its center of gravity is, and staffing and review depth should follow it.
Friction. High churn with low feature output: the same files reopened, flaky tests patched, configuration adjusted, the same bug's neighborhood visited monthly. This is attention being paid as tax. Friction churn is the most valuable signal in the map, because it marks the places where the system resists the team. It usually identifies the bottleneck the queue already knows about before any retrospective does.
Risk. High churn crossing high complexity: hotspots, the classic empirical-software result that a small share of files absorbs a large share of defects and changes. These rectangles deserve depth of review, tests, and possibly an extraction plan, in that order. A hotspot left unwatched is where What Breaks Under Scale Was Usually Present at Small Size gets its case studies.
The color variable should stay orthogonal to size: size for attention, color for outcome, coverage, defect density, review depth. One variable per channel. A map arguing two things with one color is a dashboard with a single gauge doing two jobs badly.
What this is not
Not a case against complexity metrics. Complexity, coupling, and size have their place, as inputs to risk and as second-order evidence. The argument is about the default size channel: the variable that decides what dominates the screen should measure observed attention, not accumulated mass.
Not a claim that all churn is bad. Zero churn usually means abandonment, not excellence, and the untouched-for-two-years module is its own risk story. The map's question is never "how much churn" but "what kind": load, friction, or risk. Punishing churn indiscriminately just teaches engineers to stop touching code that needs touching.
And not an argument for more dashboards. One churn map, generated weekly, looked at in one meeting, beats a portfolio of exploratory tooling nobody opens. That cadence discipline is Build the Snapshot Before the Dashboard; the map should be its own best example.
The move
- Generate two treemaps of the same codebase: one sized by lines of code, one sized by commit touches over six months. Put them side by side. The disagreement between them is the agenda for the next architecture conversation.
- Classify every large-churn rectangle as load, friction, or risk. Friction and risk rectangles get named owners and a decision: invest, stabilize, or extract.
- Re-run the churn map monthly. Watch rectangles change size. A module shrinking from friction to quiet is progress you can see; a stable module heating up is an early warning you can act on.
- When proposing investment, argue from the attention map: here is where the organization is already paying weekly. Budgets follow observed cost more readily than they follow estimates.
Take-home
- Rerun your codebase map sized by change frequency this week. The biggest rectangle will change, and the discussion that follows will be better than the one the mass map produced.
- Treat high-churn, low-output modules as the map's confession: the system is resisting the team there, and it usually already knows.
- Size is an argument. Make yours with attention, not with mass.
Related reading:
- Maps That Tell the Speed of Change
- The Bottleneck Keeps Moving
- What Breaks Under Scale Was Usually Present at Small Size
- Build the Snapshot Before the Dashboard
- Good Architecture Tracks Decisions Across Unfolding States
- Every Sync Is a Third System
If your architecture conversations keep gravitating to the biggest modules while the recurring problems live somewhere smaller and busier, the map is arguing for the past. If you want help building an attention map that shows where the work actually is, book a discovery call.
FAQ
Why size code maps by change frequency instead of lines of code?
Because size is an argument about importance, and lines of code measure history, not attention. Mass-based maps reward accretion and visually punish deletion, while churn-based maps show where the team is actually working. Attention cannot be claimed in a map, only observed in commits, which makes churn the repository's honesty signal.
What are the three kinds of churn?
Load: high change frequency from live product work, healthy attention. Friction: high churn with low feature output, the same files reopened repeatedly, attention paid as tax. Risk: high churn crossing high complexity, the classic hotspot where defects concentrate. Each implies a different response: visibility, a bottleneck decision, or review depth and extraction planning.
Isn't high churn a bad sign?
Not by itself. Zero churn usually means abandonment, and punishing churn indiscriminately teaches engineers to stop touching code that needs touching. The map's question is what kind of churn it is. Load is healthy, friction marks resistance, and risk marks hotspots that deserve depth of review before they deserve refactoring.
How often should you regenerate a churn map?
Monthly, as a snapshot with a timestamp, reviewed in one regular meeting. Watching rectangles change size over time is the real instrument: friction going quiet is visible progress, and a stable module heating up is an early warning. One attended snapshot beats an interactive dashboard nobody opens.