Boundaries and Module Coupling

Ask two engineers whether OrderPricing is cohesive and you will get opinions. Ask git and you will get data. git log --name-only --pretty=format: --since=1.year | sort | uniq -c | sort -rn over a module shows which files are edited in the same commits — and high cohesion groups code that changes together. When a pricing rule changes, the commit touches PricingRules, DiscountTable, and PricingTest and nothing else, the module is cohesive: one reason to change, one owner, one review. When the same commit routinely reaches from catalog/ into shipping/ into checkout/ to deliver one feature, low cohesion has already made three teams coordinate for one edit.

The academic phrasing — functional cohesion is best, coincidental cohesion is worst — is less useful than the operational question: what are the reasons this module's files are edited? A module with one answer ("pricing rules changed") is doing one job. A module with five answers ("shipping rules, tax tables, catalog display, export format, and a validator someone parked here in 2021") is a folder, not a module. Folders accumulate by adjacency; modules are cut by change.

Two concrete smells distinguish the cases:

A concrete exercise makes the method stick: take the last ten merged pull requests and write down the set of modules each touched. If most features touch the same small set of modules, your boundaries are drawn along the feature axis and reviews stay local. If the sets are scattered — one PR hits catalog and shipping and billing, the next hits pricing and notifications and checkout — the modules were cut by layer or by noun rather than by change, and every feature becomes a cross-team negotiation dressed up as a code review.

Repair follows the same evidence. If history says pricing and promotions co-change in 80% of feature commits, merge them — you have empirically discovered a missing context, and two halves of one cohesive unit are paying interface tax to talk to themselves. If shipping is edited for five unrelated reasons, split it along the change clusters: zones, labels, tracking, each becoming its own module with a narrow API. The reverse move matters too: an entity and everything that enforces its invariants should live together, which is the aggregate boundary of Bounded Contexts in Domain-Driven Design showing up as a measurable property rather than a diagram.

The trap in advanced systems work is optimizing cohesion in isolation. A perfectly cohesive module that nothing else can use is a well-organized orphan; cohesion says whether the inside is coherent, coupling (next chapter) says what the outside pays. Interviewers at senior level ask for both: give the history-command trick, name common/ as the anti-pattern everyone has, and finish with the repair — merge what co-changes, split what changes for unrelated reasons — before you say a word about metrics.

Cohesion describes the inside of a boundary; coupling describes the edges. Robert Martin's metrics make the edges countable, and three numbers are enough to run a design review.

Afferent coupling (Ca) counts classes outside the module that depend on it — its fan-in. High Ca means the module is load-bearing: many dependents, so every change ripples, and the API must be treated as a public contract. Efferent coupling (Ce) counts distinct modules it depends on — its fan-out. High Ce means the module cannot be understood or tested alone; it drags half the system into its classpath. Instability I = Ce / (Ca + Ce), a value from 0 (Ce = 0 — the module depends on nothing outside itself) to 1 (Ca = 0 — nothing in the system depends on it).

The design rule that gives the numbers teeth: stable components (low I) should not depend on unstable ones (high I). Concretely — if twelve modules depend on pricing (Ca = 12, Ce = 2, I ≈ 0.14, very stable), then pricing importing experimental-ml-scoring (Ca = 0, Ce = 5, I = 1.0) inverts the dependency: the stable thing now breaks when the unstable thing changes. The fix is the Dependency Inversion Principle — pricing declares the interface it needs, the unstable module implements it — which is the same consumer-owned-interface move you saw in ports and adapters, now justified with a ratio.

A worked reading from a real build:

module          Ca   Ce    I = Ce/(Ca+Ce)   reading
orders          14    3    0.18   stable, load-bearing — protect its API
pricing          5    6    0.55   balanced, but watch fan-out growth
scoring         0     7    1.00   unstable leaf — must not be depended upon
common           9    1    0.10   suspiciously stable for a junk drawer

common at Ca = 9 with a name no one can explain is the tell from the cohesion chapter: utilities become stable by fan-in, then nobody dares refactor them, and the junk drawer is financially locked in.

Ce deserves a second look during reviews because its growth is silent. Adding one import of shipping from catalog does not fail anything; it just raises catalog's Ce and its test surface. The architectural question at review time is therefore not "is this import legal?" but "does this new dependency make this module harder to test alone, and is the direction stable-to-unstable?" Direction is what separates coupling analysis from a linting exercise: an unstable module depending on a stable one (scoring importing orders) is perfectly healthy — leaves may depend on trunks, never the reverse.

Tooling makes all three numbers real: jQAssistant or ArchUnit export the dependency graph for Java, dependency-cruiser computes it for JavaScript and fails on cycles, pydeps or import-linter for Python. Feed the graph into the CI report from the last chapter and the numbers become trends. One habit makes them useful in reviews: print the three numbers for every module the PR touches, before and after. A reviewer who sees catalog move from Ce 4 to Ce 7 has a concrete question — "what did we just tie this module to, and can it still be tested alone?" — instead of a vague unease about imports. The interview payoff: "how do you know your boundaries are sound?" answered with Ca, Ce, I, direction of dependence, and one example where a ratio changed a decision — that answer is rare because most candidates stop at "low coupling, high cohesion" as adjectives rather than measurements.

orders calls billing to invoice, billing calls customers to resolve the payer, customers imports a validation helper that lives in orders. Three modules, one cycle — and the consequences are precise. No module in the cycle can be compiled or unit-tested without the other two on the classpath. A change to customers forces a joint release of all three, because orders cannot deploy against a customers version that temporarily lacks the helper. The cycle also lies about ownership: the diagram said three teams, the dependency graph said one.

Cyclic dependencies between modules block independent testing and deployment, and they are common because each edge was individually reasonable. The cure starts with detection, which is one command per toolchain:

dependency-cruiser --output-type dot src > deps.dot   # fails on cycles with --validate
cycles: npx madge --circular --extensions ts src
jQAssistant: MATCH (a)-[:DEPENDS_ON]->(b)-[:DEPENDS_ON*1..]->(a) RETURN a,b

Run it in CI as a gate, not a report: the first commit that introduces a cycle gets reverted by the build with the offending import named. Once you can see cycles, cutting them is one of exactly three moves, and choosing correctly is the architecture skill.

The event move deserves scrutiny because it is often chosen for the wrong reason: it does eliminate the compile-time edge, but it introduces eventual consistency and a delivery contract. If PlaceOrder must fail when invoicing fails, the synchronous inverted interface is honest; the event is a lie that becomes an incident. Say which you need based on whether the answer matters to the caller, not based on which looks more modern.

After the graph is acyclic, keep it that way with a trend. A CI job that writes Ca/Ce/cycle-count per module to a JSON artifact and plots the deltas per pull request changes the review conversation: "this PR adds 3 efferent couplings to checkout" is an objection a reviewer can act on, while "the design is getting worse" is not. The verification after any cut is the same three checks: the cycle query returns zero rows, each former member compiles and tests against a subset of the others, and — the check teams skip — the joint-deploy rule is gone from the release process, because a cut that leaves all three services still versioned together merely relocated the cycle to the pipeline. Architects track coupling metrics over time to detect boundaries eroding under deadlines because erosion is a rate, not an event — no single import ruined anything; forty imports across sixty days did, and only the trend line shows the slope. This measurement habit is what you carry into the next phase: microservice boundaries magnify every one of these numbers into network calls, so getting fluent here on one deployable is the cheapest place to learn it.