What is the "main sequence" on the Abstractness/Instability graph, and how is a component's distance D from it computed and interpreted?

### Setting up the graph For each component (a package/module/JAR — a unit you can release independently) compute two ratios: - **I (Instability) = Ce / (Ce + Ca)** where Ce = outgoing dependencies (types inside depending on types outside) and Ca = incoming dependencies (types outside depending on types inside). I = 0 means nothing can force it to change but many depend on it; I = 1 means nothing depends on it and it depends on others. - **A (Abstractness) = Na / Nc** where Na = interfaces + abstract types, Nc = total types. A = 0 fully concrete, A = 1 pure contract. Plot I horizontally, A vertically. Every component is a dot inside the unit square [0,1] × [0,1]. ### The two good corners and the line between them Only two corners of the square are healthy: - **(I=0, A=1)** — maximally stable *and* maximally abstract. Everyone depends on it, and it is pure interface, so it can be extended by adding new implementations without modifying it. Think of a `payments-api` module of interfaces and value types. - **(I=1, A=0)** — maximally unstable *and* fully concrete. Nobody depends on it, so its concreteness costs nothing and it is free to change. Think of the application's `main`/composition root or a UI shell. The straight line joining those two corners is `A + I = 1` — the **main sequence** (the name is borrowed from the astronomers' Hertzsprung–Russell diagram, where normal stars fall along a diagonal band). It states the ideal trade-off: **a component's abstractness should be proportional to its stability**. Not every component must be at an endpoint; a mid-line point like (I=0.5, A=0.5) — partly abstract, moderately depended-upon — is perfectly balanced. ### The distance metric D ``` D = |A + I − 1| / √2 (original: perpendicular distance, range 0 .. 0.707) D' = |A + I − 1| (normalized, range 0 .. 1) ← what most tools report ``` Modern tooling almost always reports the normalized form and simply calls it D. Because the sign is dropped by the absolute value, D alone does **not** say *which* way a component is off-balance — you must look at A + I − 1: - **A + I − 1 < 0** → the point is *below* the line, drifting toward **(0,0)**: stable and concrete — the **zone of pain**. Many depend on it, and it is all implementation, so changes are expensive and rippling. - **A + I − 1 > 0** → the point is *above* the line, drifting toward **(1,1)**: unstable and abstract — the **zone of uselessness**. Abstractions nobody uses; dead weight. Some authors add a signed variant, **distance D̂ = A + I − 1** (range −1..+1), precisely so the direction is preserved. ### Worked examples | Component | Ce | Ca | I | Na/Nc | A | A+I−1 | D | Reading | |---|---|---|---|---|---|---|---|---| | `order-api` (interfaces) | 0 | 24 | 0.00 | 9/9 | 1.00 | 0.00 | 0.00 | on the line, ideal contract | | `web-ui` | 11 | 0 | 1.00 | 0/30 | 0.00 | 0.00 | 0.00 | on the line, ideal leaf | | `core-util` | 1 | 40 | 0.02 | 0/26 | 0.00 | −0.98 | 0.98 | deep in the zone of pain | | `legacy-abstractions` | 6 | 0 | 1.00 | 7/7 | 1.00 | +1.00 | 1.00 | zone of uselessness | | `billing` | 5 | 5 | 0.50 | 3/12 | 0.25 | −0.25 | 0.25 | mildly concrete-heavy, acceptable | ### How to actually use D 1. **Rank, don't gate on an absolute.** Sort components by D descending and look at the top few. A blanket rule like "D < 0.2 for every module" produces interface-for-interface's-sake churn. 2. **Watch the trend.** D rising release over release for a given component is far more informative than its instantaneous value. Some teams chart mean D and its variance as an architectural fitness function in CI. 3. **Check direction and volatility together.** High D toward (0,0) only *hurts* if the component actually changes. A concrete, universally-depended-on, and utterly frozen component (a string library, a stable wire-format DTO set) has a terrible D and no problem — this region is sometimes called the **zone of exclusion**'s benign neighbour, and Martin explicitly notes that non-volatile concrete components are fine there. 4. **Remember boundaries dominate.** Splitting or merging modules changes Ce, Ca, and Nc at once. If a module is off the line, one legitimate fix is *repackaging* — e.g. extracting its interfaces into their own component (pushing that new component to A≈1, I≈0) and leaving the implementations in a concrete, unstable one. ### Caveats - D says nothing about **cohesion**, **cycles**, or whether abstractions are used for real dependency inversion — an interface implemented by exactly one class in the same module raises A without buying anything. - Components with very few types produce wildly noisy A (a 2-type module jumps 0 → 0.5 → 1). - Generated code, test modules, and DTO/protobuf packages skew results and are usually excluded.