nwiizo Balanced Coupling Model Reference
Based on Vlad Khononov's "Balancing Coupling in Software Design".
The Balance Rule
MODULARITY = STRENGTH XOR DISTANCE
COMPLEXITY = STRENGTH AND DISTANCE
BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY
- Modularity emerges when strength and distance counterbalance
- Complexity emerges when both are equal (both high or both low)
- Pragmatic: unbalanced coupling is tolerable if volatility is low
Three Dimensions
1. Integration Strength (Knowledge Shared)
From most to least intrusive:
| Level | Knowledge Type | Implicit/Explicit |
|---|---|---|
| Intrusive | Implementation details, private interfaces | Implicit, fragile |
| Functional | Business rules, functional specifications | Often implicit |
| Model | Domain/business model, data structures | Explicit but broad |
| Contract | Integration contracts, facades | Most explicit, stable |
Key insight: Intrusive and Functional coupling are often implicit — they exist without anyone realizing. Contract coupling is explicit by design.
2. Distance (Cost of Change)
Multiple dimensions contribute to distance:
- Code structure: methods → objects → modules → crates → services
- Organizational: same team vs different teams (Conway's Law)
- Runtime: synchronous (tight) vs asynchronous (loose)
- Lifecycle: shared deployments vs independent deployments
Distance is fractal: the same rules apply at every abstraction level.
3. Volatility (Probability of Change)
Determined by DDD subdomain classification, not just git history:
| Subdomain | Volatility | Reason |
|---|---|---|
| Core | High | Competitive advantage, constantly optimized |
| Supporting | Low | Boring CRUD/ETL, rarely changes |
| Generic | Low | Solved problems, stable implementations |
Important: distinguish essential vs accidental volatility. Accidental volatility comes from poor design, not business needs.
Configure this in .coupling.toml:
[subdomains]
core = ["src/balance.rs", "src/metrics.rs"]
supporting = ["src/analyzer.rs", "src/report.rs"]
generic = ["src/config.rs", "src/web/**"]
Issue Classification
| Pattern | Strength | Distance | Volatility | Severity |
|---|---|---|---|---|
| High Cohesion | Strong | Close | Any | Ideal |
| Loose Coupling | Weak | Far | Any | Ideal |
| Acceptable | Strong | Far | Low | Minor |
| Global Complexity | Strong | Far | High | Critical |
| Local Complexity | Weak | Close | Any | Review |
| Hidden Coupling | Temporal co-change | No code edge | Medium/High | Medium/High |
| Accidental Volatility | Any | Any | Supporting/Generic churn | Medium |
Hidden Coupling indicates strong co-change without a direct AST dependency, often duplicated business logic or connascence of meaning/algorithm. Accidental Volatility indicates high churn where the subdomain classification says volatility should be low.
Recognition Rules (avoid false positives)
The balance rule only condemns coupling when volatility is genuinely high. Apply these so the signal stays trustworthy:
- Essential vs accidental volatility: subdomain (
.coupling.toml) volatility is authoritative for scoring. Raw git churn from a development sprint is accidental — it feedsAccidentalVolatilityonly, and must not create Cascading Change Risk on a low-essential-volatility target. - Severity by volatility: Strong + Far + High = Global Complexity (act now); Strong + Far + Low = Acceptable (Minor — low volatility neutralizes the distance).
- Entrypoint (
crate::main): high efferent fan-out and co-change with wired modules are expected by design → not a defect / not hidden coupling. - Re-export facade (
crate::crate_name=lib.rs): a stable Contract; coupling to it is not intrusive coupling to a volatile component. - Stable central abstraction: high afferent coupling is good design; only risky when the hub is itself volatile (scale severity by the hub's essential volatility).
Analysis Manifest
cargo-coupling declares blind spots for static analysis. Text output can expand them with --blind-spots; --json and --ai include the full manifest. Use this when interpreting a clean report.
Connascence Refinement
Within each strength level, connascence types provide finer granularity:
Static (compile-time): Name → Type → Meaning → Position → Algorithm Dynamic (runtime): Execution → Timing → Values → Identity
Stronger connascence = harder to change = higher coupling cost.
Pragmatic Balancing
- Not all unbalanced coupling needs fixing — prioritize by volatility
- Low volatility neutralizes unbalanced coupling
- Focus refactoring on core subdomains (highest business value)
- Distance increases lifecycle coupling (deployment constraints)
For detailed reference: model-reference.md