Package and Component Principles

CCP says: put into one component the classes that change for the same reasons and at the same times. Then a typical change touches one component instead of many, so you rebuild, retest and redeploy less.

CRP says classes that are used together should be packaged together, and classes that are not used together should not be. It keeps consumers from depending on, rebuilding, and redeploying code they never use.

Instability I = outgoing dependencies / (outgoing + incoming). It says how easily a component can be forced to change. Abstractness A = abstract types / all types. It says how much of the component is interfaces rather than concrete code. Both run 0 to 1.

REP says the granule of reuse is the granule of release: the unit you reuse must be the unit you release. A component has to be published as a versioned whole, with a version number and release notes, so consumers depend on a specific version instead of copying files.

SAP says: the harder a component is to change because many others depend on it, the more abstract it should be. Stable components should expose interfaces/abstract types; volatile, concrete code belongs in components few things depend on.

The Stable Dependencies Principle says a component should depend only on components that are more stable than it. "Stable" means hard to change — lots of other things depend on it — not "never changes".

Two options. (1) Apply the Dependency Inversion Principle: put an interface that C needs into C (or a place C already sees), and have A implement it — the arrow A → B → C → A becomes C ← A with no return edge. (2) Extract the shared code into a new component D that both A and C depend on.

With layer packages, adding one feature field forces edits in every layer package at once. CCP wants classes that change together in one component, so it favours grouping by feature or business capability, with layers inside each feature.

CRP is ISP one level up: ISP says don't make a client depend on methods it doesn't use; CRP says don't make it depend on classes it doesn't use. CCP is different — it groups classes that change together, not classes used together.

Plot Abstractness A against Instability I. The main sequence is the line A + I = 1, running from abstract-and-stable (0,1) to concrete-and-unstable (1,0). Distance D = |A + I − 1|; 0 is ideal, 1 is worst.

The component has no coherent theme: nobody reuses all four things together, yet everyone shares one version. Any change forces unrelated consumers to see new versions and possibly breaking bumps. Split it into themed, separately versioned components with their own release notes.

Count the component's abstract types (interfaces and abstract classes) as Na and all its types as Nc; A = Na/Nc, from 0 to 1. A = 0 means entirely concrete implementation; A = 1 means nothing but interfaces, no implementation at all.

Count outgoing dependencies (Ce) and incoming ones (Ca), then I = Ce / (Ca + Ce). I = 0 means maximally stable, I = 1 maximally unstable. SDP holds when each component's I is greater than or equal to the I of everything it depends on.

REP and CCP make components bigger (easier to reuse and to change in one place); CRP makes them smaller (consumers shouldn't carry what they don't use). You can't maximise all three, so you pick a point: young projects lean CCP, mature shared libraries lean REP and CRP.

Invert the dependency: define the needed operation as an interface owned by (or extracted next to) the stable side, have the volatile component implement it, and inject the implementation at runtime. The compile-time arrow now points from volatile to stable.

Topologically sort the dependency graph: build components with no unbuilt dependencies first, then their dependents, and so on. A cycle has no such starting point — each member waits on another — so no valid order exists and the whole loop must be built and released as one unit.

Depending on a component means depending on its whole release: you inherit its transitive libraries, its version constraints, its vulnerabilities, and you must re-test and redeploy every time it releases — even for changes to code you never call.

The zone of pain is the corner near Instability=0 and Abstractness=0: a component that everything depends on and that contains only concrete code. Changing it is expensive and ripples everywhere. It's fine only if that component essentially never changes.

SDP says depend in the direction of stability — point dependencies at things that are hard to change. SAP says those stable things should be abstract. Put together: dependencies flow toward abstractions, which is exactly what the Dependency Inversion Principle asks for, applied to whole components.

No. Stability measures how hard a component is to change (how many things depend on it), while volatility is how often it actually changes. A frequently-edited component with many dependents is stable and volatile at once — the dangerous combination.

Don't rely on code review — a loop can span five components and be invisible in a diff. Add an automated dependency check to CI that fails the build on any cycle (ArchUnit/Spring Modulith, dependency-cruiser, import-linter, jdeps, NDepend), fix violations immediately, and keep a documented, owned component map.

Mine version-control history: find files that keep changing in the same commits but live in different components. That temporal coupling is direct evidence the boundary cuts across a real axis of change, so move or merge those parts.

CCP is inclusive - it pulls classes together so one change hits one component. CRP is exclusive - it splits out classes that consumers don't use, so nobody depends on code they don't need. You balance them, favouring CCP early and CRP once code is widely reused.

Measure which classes each consumer actually uses, cluster by observed joint usage, split into one artifact per cluster, and keep the old artifact as a thin aggregator that depends on the new ones so nothing breaks. New costs: more versions, releases, pipelines and coordination.

It is stable and concrete — many modules depend on it, it has no interfaces, and it keeps changing. Extract its interfaces into a new contract module that dependents import, leave the concrete code in an implementation module nobody depends on, and split it by reason to change.

It's the corner near Instability=1 and Abstractness=1: a component full of interfaces and abstract types that nothing depends on. The abstractions exist but nobody uses them, so the code is dead weight — usually leftovers or speculative design.

Not necessarily. REP demands that reuse happen through a defined, identifiable release. In a monorepo built at HEAD, the commit itself is the release: one version for everything, atomic changes, no pinning. It satisfies REP's intent only if boundaries, ownership and change communication still exist.

REP, CCP and CRP pull in different directions. REP and CCP push components larger (releasable, coherent, co-changing); CRP pushes smaller (don't force consumers to depend on things they don't use). You pick a spot on that triangle that suits the project's current stage, then revisit it.

Plot abstractness A against instability I. The Main Sequence is the line A + I = 1 — the healthy balance. D = |A + I - 1| measures how far off it a component sits (0 = on the line). The two bad corners are stable-and-concrete (Zone of Pain) and abstract-with-no-dependents (Zone of Uselessness).