The model: a build is a graph, change is a distribution

From the survey we have the first half: a build is a directed graph $G = (V, E)$ whose nodes are units of compilation (files, modules) and whose edges $u \to v$ mean "$v$ depends on $u$" — change $u$ and $v$ may need rebuilding. A build system, given a changed node, rebuilds its dependents: everything reachable by following edges forward.

The second half is the part most discussions of modularity skip. Code doesn't change uniformly. Some modules churn constantly (business policy, UI copy); others are touched once a year (a hashing primitive, a parser for a frozen format). The rebuild cost is driven by the change probability $p(m)$ of the edited module — and on a real project you don't have to guess $p(m)$: it is the file's commit frequency in git log.

With those two pieces — the graph and the change distribution — "optimal" stops being a matter of taste.

What "optimal" means, precisely

Let $D(m)$ be the set of dependents of module $m$, and let $c(m)$ be the cost of rebuilding $m$ (compile time, say). When an edit lands in $m$, the build system pays to rebuild $m$ and everyone downstream of it. The expected rebuild cost of the whole codebase, per unit time, is the sum over every module of "how often it changes" times "what that change costs to rebuild":

$$\mathrm{Cost}(G) = \sum_{m} p(m) \cdot \!\!\sum_{d \,\in\, \{m\} \cup D(m)} \!\! c(d).$$

Read it in plain terms: a module hurts in proportion to how often it changes multiplied by how much sits downstream of it. A hashing-library node has a large downstream cone but a tiny $p$ — it's cheap, because it never changes. A business-rules node changes daily but sits at a leaf with no dependents — also cheap. The expensive nodes are the ones that are both frequently changed and widely depended on. That product, $p(m) \cdot |D(m)|$, is the rebuild tax of a module.

Because the tax is a product, it can be drawn honestly: one factor is a height, the other a width, and the cost is an area. Here are those three characters to scale — drag either factor and watch what the area does:

An optimal set of module boundaries is one that minimizes $\mathrm{Cost}(G)$ over the ways you could partition the same functions into modules — given that you can't change what the code does, only how it's grouped and who depends on whom. Refactoring for incremental builds is exactly the search for that minimum.

Why utils is provably slow

Now the pathology falls out of the formula. A utils module fuses functions that change for unrelated reasons — the datetime helper, the parser, the formatter. Two consequences, both bad for $\mathrm{Cost}(G)$:

1. Its change probability is the union of its parts. A module changes if any of its functions changes, so $p(\text{utils}) \approx p(\text{datetime}) + p(\text{parse}) + p(\text{format}) + \dots$ — approximately the sum, because each reason fires rarely. (Precisely: the chance that at least one part changes is $1 - \prod_i (1 - p_i)$ — one minus the chance that every part stays quiet, where $\prod$ multiplies those stay-quiet chances together. The plain sum is always at least that, and nearly equals it when each $p_i$ is small — the union bound.) Lumping raises $p$.
2. Everyone depends on all of it. Because file-granularity build systems track dependencies per file, every consumer of any function in utils is a dependent of the whole file. So $D(\text{utils})$ is the union of the dependents of every function inside it — large.

A module with both a high $p$ (everything's reasons, summed) and a large $D$ (everyone, unioned) is precisely the high-rebuild-tax node the objective tells us to eliminate. Edit the one-line datetime helper and the parser, the formatter, and everything downstream of the entire file rebuilds — work that the change-reasons had nothing to do with.

Slide the split again, now that the tax has a name — the same figure from the top of the piece, twenty-four consumers, one utils, and $k$ under your control:

The refactorings, as algorithms

"Improve cohesion" is advice; an algorithm is something you can run. Here are the moves that lower $\mathrm{Cost}(G)$, each stated as a deterministic procedure over the graph.

SPLIT-BY-CHANGE-REASON(M, H)
Input:  module M with functions f[1:n], history H
Output: partition of M into cohesive modules

groups ← EMPTY-PARTITION
for i ← 1 to n
    reason ← ESTIMATE-REASON(f[i], H)
    groups ← ADD(groups, reason, f[i])
return EMIT-MODULES(groups)

INVERT-VOLATILE-DEPENDENCY(stable, volatile)
Input:  stable → volatile; volatile changes often
Output: volatile → I ← stable via interface I

required ← USED-OPERATIONS(stable, volatile)
I ← DEFINE-INTERFACE(required)
stable′ ← DEPEND-ON(stable, I)
volatile′ ← IMPLEMENT(volatile, I)
return (stable′, volatile′, I)

DELETE-INTERNAL-BARREL(B, consumers)
Input:  barrel B, modules M[1:k], internal consumers
Output: consumers importing from defining modules

for each consumer C in consumers
    for each symbol s that C imports from B
        owner ← DEFINING-MODULE(s, M)
        C ← REWRITE-IMPORT(C, s, owner)
if B is not a public API boundary
    DELETE(B)
return consumers

RANK-BY-REBUILD-TAX(M)
Input:  modules M[1:n], change rates p, dependents D
Output: modules in descending rebuild-tax order

for i ← 1 to n
    tax[i] ← p(M[i]) · |D(M[i])|
return STABLE-SORT-DESCENDING(M, tax)

Why the drawer fills anyway

The four moves fix the utils you have. They don't explain why you'll have another one next year. Every codebase grows the drawer, which means the forces that fill it are stronger than the review culture guarding it — and a fix that doesn't name those forces is treating the symptom.

• The name is a deferral. Nothing lands in utils because it belongs there; it lands at the moment its author decides that figuring out where it belongs isn't worth the interruption. The module is named for what the code isn't — not parsing, not UI, not the domain — and "not" is not a change-reason. In the objective's terms: utils is where functions with an unlabeled $r(f)$ accumulate, and unlabeled reasons are exactly the ones that end up fused.
• The friction is asymmetric. Appending to utils.py is one edit. A new module is a name to invent, a file, an import path, sometimes a build rule — and a review conversation about all four. Under deadline the cheap path wins every time; the drawer isn't a lapse of discipline, it's the equilibrium of that asymmetry.
• Review pressure points the wrong way. The same reviewer who will spend three comments on a new module's name waves a helper into utils without one. Each wave-through teaches the next author where code goes to avoid questions.

The countermeasures are the forces, inverted — one each:

1. Park it next to its only caller. A helper with one caller needs no home: it lives in the caller's file and inherits the caller's change-reason, and the build graph sees nothing new. Move it out on the second unrelated caller — a cousin of the rule of three — because two real callers are the first evidence of what the helper actually is: what they share names the module.
2. Ban the names, not the helpers. utils, helpers, common, misc as a path segment is a confession that the change-reason is missing — so make the confession loud. A lint rule that rejects those path names turns a silent deferral into a visible decision at review time. The helper is welcome; the label "unlabeled" is not.
3. Make the right thing as cheap as the wrong one. The drawer wins on friction, so lower the other side's: a one-command module scaffold, and a norm that a one-function module with an honest name is normal. The graph doesn't mind small files; it minds fused reasons (the over-splitting caveat below still stands — stop at cohesive, not atomic).
4. If you keep an inbox, give it a zero policy. Where a landing zone genuinely helps, treat it like an inbox: things may land, nothing may live. Cap its size in lint and drain it by move 4's triage — highest $p \cdot |D|$ first.

The common thread is a feeling, and the feeling is data. The discomfort you carry about utils is the deferred decision — the open loop of a naming you skipped. Hating the module is a defense mechanism in the strict sense, and it's load-bearing: the hate is what remembering a deferral feels like, and it protects you from the real failure mode, which is comfort. A team at peace with its junk drawer has stopped noticing that it defers, and from there the tax compounds quietly. The formula gives the instinct its number; the instinct is still what fires first.

How to find your own utils problem

You don't have to guess which module to fix. The cost function hands you the procedure: compute the rebuild tax of every file and look at the top.

• $p(m)$ — count commits touching the file over some window: git log --oneline -- path/to/file | wc -l.
• $|D(m)|$ — the number of files that depend on it (your build system's dependency graph, or a static import scan).
• Rank by the product. The high-tax, top-right quadrant — frequently changed and widely depended on — is your utils, whatever it's called. Split those by change-reason first; the long tail of low-tax modules can wait forever.

# Every node and edge, one JSON object per line.
bazel query 'deps(//...)' --output=streamed_jsonproto

# What one file invalidates — and just the tests among them.
bazel query 'rdeps(//..., //path/to:file.ext)' --output=label_kind
bazel query 'kind(".*_test", rdeps(//..., //path/to:file.ext))'

# Why an edge exists at all, when a dependent looks wrong.
bazel query 'somepath(//consumer:target, //suspect:target)'

bazel aquery 'deps(//...)' --output=jsonproto

Check whether you're rebuilding at all

$\mathrm{Cost}(G)$ quietly assumes that everything invalidated is rebuilt. Under a content-addressed cache that assumption is false: an invalidated node whose inputs have been seen before is restored, for the price of a hash lookup and a copy. The honest cost carries a term the formula leaves out:

$$\mathrm{Cost}(G) = \sum_{m} p(m) \cdot \!\!\sum_{d \,\in\, \{m\} \cup D(m)} \!\! c(d) \,(1 - h(d)).$$

where $h(d)$ is the chance that $d$'s inputs already resolve to a stored result.

The two factors are independent levers. Splitting a module shrinks $|D(m)|$. Turning on a cache shrinks the multiplier on every $|D(m)|$ you already have — including all the ones you were never going to refactor. One is a line of configuration; the other is weeks of restructuring.

That ordering is uncomfortable for an essay about module boundaries, so let me state it plainly: if your builds are slow and nothing persists between them, your boundaries are not the first problem. A cache that does not survive a server restart, a branch switch, or a second checkout of the same commit is a cache you are not getting paid for. Check for one before you reach for the refactor — the check takes a minute, and it can save you the month.

None of which rescues utils. A cache lowers the cost of rebuilding what you invalidate; it does not lower what you invalidate. And a drawer that changes daily generates misses by construction, because its key changes whenever any one of its unrelated functions does — the same fusion, now expressed as a cache-miss rate instead of a rebuild count. The levers compose: cache what recurs, split what doesn't. Pull the cheap one first, then measure again before pulling the expensive one.

The honest limits

The model is a lamp, not a law. Three caveats:

• It needs estimated change probabilities, which means predicting the future from the past. git log is a good prior, not a guarantee; a module quiet for a year can suddenly become hot.
• Over-splitting has its own cost the formula doesn't capture. A thousand one-function modules minimize rebuild tax and maximize navigation and ceremony pain. The objective bounds the build cost, not the human cost; stop splitting when modules are cohesive, not when they're atomic.
• Granularity has two bounds, and your toolchain is rarely the binding one. The floor is the finest unit your build system can observe — the file for most (C++ does so even for headers, as the survey noted), the crate for Rust, the package for Go. Function-level incremental compilers move the floor down, and you can't refactor below it. But there is a second bound above it: the ceiling, the coarsest unit your own build files impose on top of that floor — and the ceiling is what usually binds. A toolchain that computes per-object dependencies still wakes everything if every test links one archive. A language with per-module tracking still fuses the lot if one build target globs the whole source tree. In those cases the finer granularity provably exists: the tool computed it, and the build definition threw it away. Find out which bound is binding before concluding you've hit a limit.

Lessons

• A build is a graph; change is a probability distribution over its nodes. Module design is the act of shaping both.
• Optimal has a definition: minimize $\mathrm{Cost}(G) = \sum_m p(m) \cdot \sum_{d \in \{m\} \cup D(m)} c(d)$. A module's rebuild tax is $p(m) \cdot |D(m)|$.
• utils is provably expensive: lumping unrelated functions sums their change probabilities and unions their dependents — high $p$ and large $|D|$ at once, the worst corner of the objective.
• The refactorings are deterministic algorithms: split by change-reason, invert volatile dependencies, kill barrel files, keep hubs stable.
• To find what to fix, rank files by $p(m) \cdot |D(m)|$ (git churn $\times$ dependents) and start at the top. Take $|D(m)|$ from the build system's graph, not an import scan — the build's edges are the ones that gate work.
• Check the cache before you split anything. $\mathrm{Cost}(G)$ assumes invalidated means rebuilt; a content-addressed cache makes it mean restored, multiplying every dependent cone by $(1 - h)$. Shrinking $|D|$ and shrinking the multiplier are independent levers, and the second one is a line of configuration.
• Fan-out alone can't see the worst unit. A single action holding three thousand tests counts as one dependent. Compute the dual — inputs per action — or the coarsest thing you own will rank last on the metric built to find it.
• One invalidation class means the unit is indivisible. Counting the distinct dependent sets in a directory needs no change history and costs one query. But normalize by compilation unit first: a Rust crate or a Go package with one class is at its floor, not in a drawer.
• Your build files set a ceiling above the toolchain's floor, and the ceiling usually binds. Per-object compilation fused into one archive, or per-module sources fused by a whole-directory glob, throws away granularity the tool already computed.
• The drawer fills because deferral is cheap and naming is not. Invert the friction: park a helper beside its only caller, move it out on the second unrelated caller, reject utils-family path names in lint, and give any landing zone a zero-resident policy. Distrust comfort with the drawer more than you distrust the drawer.

Practice

References

1. M. Conway. “How Do Committees Invent?.” 1968. — the original Conway's Law paper
2. “Single-responsibility principle.” — and dependency inversion — the same ideas, stated without the build graph
3. “Cohesion.” — and coupling, for the classic vocabulary
4. “Rule of three.” — when a helper has earned a home of its own
5. “The Build Is Proportional to the Change.” — where the build-graph model comes from

Mangalapilly, Y. J. (2026, June). Utils Is Where Modularity Goes to Die. Saṃhitā Notes. https://yesudeep.com/blog/utils-is-where-modularity-goes-to-die/

@online{mangalapilly2026utils,
  author  = {Yesudeep Jose Mangalapilly},
  title   = {Utils Is Where Modularity Goes to Die},
  journal = {Sa\d{m}hit\=a Notes},
  year    = {2026},
  month   = {June},
  url     = {https://yesudeep.com/blog/utils-is-where-modularity-goes-to-die/},
  urldate = {2026-08-20},
}

Yesudeep Jose Mangalapilly. “Utils Is Where Modularity Goes to Die.” Saṃhitā Notes, 2026. https://yesudeep.com/blog/utils-is-where-modularity-goes-to-die/.

TY  - ELEC
AU  - Mangalapilly, Yesudeep Jose
TI  - Utils Is Where Modularity Goes to Die
T2  - Saṃhitā Notes
PY  - 2026
UR  - https://yesudeep.com/blog/utils-is-where-modularity-goes-to-die/
Y2  - 2026-08-20
ER  -