Diagnosing Coupling
In this pack:
sizing,
notation,
rule strictness.
Overview
Coupling is the cost of a change spreading: two parts are tied when a
change to one forces a change to the other. This skill names the tie,
weighs how strong and how widespread it is, and uses the change history
to decide which tie to loosen first. It treats ladders and metrics as
places to look, not as scores to chase.
When to use
- A change to one behaviour keeps editing several classes or modules.
- A part is hard to change or test without bringing its neighbours.
- A review asks how tightly two classes or modules are tied.
- A refactor needs an order: which tie to loosen first.
- A module boundary needs a stability check.
When not to use
- The question is where one new behaviour belongs, not how two existing
parts are tied. That is assigning responsibilities.
- The change is a one-line fix or a throwaway script. Fix it and stop.
- There is no code yet to measure. A new design starts from sizing in
the index.
Core rules
Rule. Name the tie before judging it: connascence is what must
change together. Two parts share connascence when a change to one
forces a change to the other. Naming the agreement, instead of
calling the pair "tightly coupled", gives the next rule something to
order.
Rule. Look for the static kinds in the code: name, type, meaning,
position, algorithm. Name is a method or field both sides spell.
Type is a type both sides accept. Meaning is a convention both sides
read into a value, such as a magic number. Position is the order of
arguments. Algorithm is a step both sides repeat and must keep in
step.
Rule. Then look for the dynamic kinds, which show only at run
time: execution order, timing, value, identity. Execution order is
a sequence calls must follow. Timing is a moment they must meet.
Value is a set of values that must agree. Identity is the same
object, not a copy. The nine kinds run name, type, meaning, position,
algorithm, execution order, timing, value, identity; each dynamic
kind is stronger than any static one.
Rule. Weigh a tie by strength, locality and degree. Strength
follows the kind: later kinds in the order are stronger, and dynamic
beats static. Locality asks where the tie sits; the same kind costs
less inside one class than across modules. Degree counts how many
elements share it. A strong tie in one method can be cheaper than a
weak tie repeated in twelve classes.
Default. Refactor toward the weaker, more local, lower-degree
tie. Position becomes name through a parameter object or named
fields. Meaning becomes type through a value type or an enum instead
of a magic value. A duplicated algorithm gets one owner and the
other copies delegate.
The exception is a tie set by an outside format or protocol. Wrap
that tie at the boundary and keep it out of the domain model.
Judgement. Loosen the strongest tie that the most modules share
first. Strength, degree and locality decide together. The first
candidate is the strongest tie shared most widely across modules; a
weaker tie inside one class can wait.
Rule. Label a module tie on the coupling ladder, tightest first:
content, common, external, control, stamp, data. Content reaches
into another module's internals. Common shares global data. External
follows a fixed outside format or protocol. Control passes a flag
that steers the callee. Stamp passes a whole structure where a part
is needed. Data passes only the values needed. Use the rungs as
diagnostic labels, not as a score.
Rule. Label what holds a class together on the cohesion ladder,
weakest first: coincidental, logical, temporal, procedural,
communicational, sequential, functional. Coincidental has no
theme. Logical groups by kind of thing. Temporal groups by when it
runs. Procedural groups by a shared sequence. Communicational works
on the same data. Sequential feeds one part's output to the next.
Functional has every part serving one task. A class held together
only by kind or by timing is a candidate to split.
Rule. Read package dependency counts as afferent, efferent and
instability. Afferent counts how many modules depend on this one.
Efferent counts how many it depends on. Instability is
efferent / (afferent + efferent), from 0 for stable to 1 for
unstable. Treat the counts as places to look, not as targets.
Default. Depend in the direction of stability. A module many
others depend on should not depend on volatile details. Point each
dependency from the less stable module toward the more stable one.
The exception is a boundary adapter whose job is to meet a volatile
outside system. Keep it at the edge and keep the stable core clear
of it.
Rule. Measure before judging. Evidence is what changes together
in the version history, the size of the change a typical request
causes, and dependency counts. A coupling smell becomes a finding
only with such evidence; without it, the red flags below are places
to look.
Pattern
Before, BillingDesk calls InvoiceBuilder.build(visit, "AXA", 2, true).
"AXA" is an insurer code that billing and claims must spell the same
way, 2 is the plan tier, and true means lab fees are included. The
call carries connascence of meaning, because the bare code and tier are
conventions, and connascence of position, because the caller must
remember which slot is which. The flag also steers the builder's logic,
which is control coupling.
Before:
class BillingDesk
- invoices: InvoiceBuilder
+ new(invoices: InvoiceBuilder)
+ invoice(visit: Visit): Invoice
return invoices.build(visit, "AXA", 2, true)
class InvoiceBuilder
+ build(visit: Visit, insurer: String, tier: Int, labFees: Boolean): Invoice
return new Invoice(visit, insurer, tier, labFees)
After, InvoiceBuilder.build(visit, coverage) takes one Coverage.
The insurer code is an InsurerCode, the tier is a PlanTier, and the
lab-fee choice is a LabFees. The three parts are named, so a caller
cannot put the tier where the insurer belongs, and the flag no longer
reaches the builder as a bare switch.
After:
value InsurerCode
- code: String
+ new(code: String)
enum PlanTier
Basic
Family
enum LabFees
Excluded
Included
value Coverage
- insurer: InsurerCode
- tier: PlanTier
- labFees: LabFees
+ new(insurer: InsurerCode, tier: PlanTier, labFees: LabFees)
class BillingDesk
- invoices: InvoiceBuilder
+ new(invoices: InvoiceBuilder)
+ invoice(visit: Visit, coverage: Coverage): Invoice
return invoices.build(visit, coverage)
class InvoiceBuilder
+ build(visit: Visit, coverage: Coverage): Invoice
return new Invoice(visit, coverage)
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A request that keeps touching the same set of files across different
modules.
- A boolean or mode parameter that switches the callee's behaviour.
- A parameter list of several values of the same type whose order
matters.
- A magic value that two modules must spell the same way.
- Two classes whose version history shows changes in the same commits.
- A module many others depend on that depends on a volatile detail.
Common mistakes
- Treating a metric as a target and refactoring until the number moves.
- Trying to remove all coupling. Parts that work together must know
something about each other; the goal is a weaker, more local tie.
- Counting imports and missing connascence of meaning, timing or
algorithm that no import shows.
- Splitting a cohesive class only because it is long.
- Reading high instability as a defect. A leaf module with no dependants
is meant to be unstable.
Related skills
Further reading
- Connascence
- Coupling and cohesion ladders
1---2name: oo-diagnosing-coupling3description: Use when a change ripples through many classes, a part is hard to change or test alone, or you need to judge how tightly two parts are tied.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-diagnosing-coupling7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Diagnosing Coupling1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920Coupling is the cost of a change spreading: two parts are tied when a21change to one forces a change to the other. This skill names the tie,22weighs how strong and how widespread it is, and uses the change history23to decide which tie to loosen first. It treats ladders and metrics as24places to look, not as scores to chase.2526## When to use2728- A change to one behaviour keeps editing several classes or modules.29- A part is hard to change or test without bringing its neighbours.30- A review asks how tightly two classes or modules are tied.31- A refactor needs an order: which tie to loosen first.32- A module boundary needs a stability check.3334## When not to use3536- The question is where one new behaviour belongs, not how two existing37 parts are tied. That is assigning responsibilities.38- The change is a one-line fix or a throwaway script. Fix it and stop.39- There is no code yet to measure. A new design starts from sizing in40 the index.4142## Core rules43441. Rule. **Name the tie before judging it: connascence is what must45 change together.** Two parts share connascence when a change to one46 forces a change to the other. Naming the agreement, instead of47 calling the pair "tightly coupled", gives the next rule something to48 order.49502. Rule. **Look for the static kinds in the code: name, type, meaning,51 position, algorithm.** Name is a method or field both sides spell.52 Type is a type both sides accept. Meaning is a convention both sides53 read into a value, such as a magic number. Position is the order of54 arguments. Algorithm is a step both sides repeat and must keep in55 step.56573. Rule. **Then look for the dynamic kinds, which show only at run58 time: execution order, timing, value, identity.** Execution order is59 a sequence calls must follow. Timing is a moment they must meet.60 Value is a set of values that must agree. Identity is the same61 object, not a copy. The nine kinds run name, type, meaning, position,62 algorithm, execution order, timing, value, identity; each dynamic63 kind is stronger than any static one.64654. Rule. **Weigh a tie by strength, locality and degree.** Strength66 follows the kind: later kinds in the order are stronger, and dynamic67 beats static. Locality asks where the tie sits; the same kind costs68 less inside one class than across modules. Degree counts how many69 elements share it. A strong tie in one method can be cheaper than a70 weak tie repeated in twelve classes.71725. Default. **Refactor toward the weaker, more local, lower-degree73 tie.** Position becomes name through a parameter object or named74 fields. Meaning becomes type through a value type or an enum instead75 of a magic value. A duplicated algorithm gets one owner and the76 other copies delegate.7778 The exception is a tie set by an outside format or protocol. Wrap79 that tie at the boundary and keep it out of the domain model.80816. Judgement. **Loosen the strongest tie that the most modules share82 first.** Strength, degree and locality decide together. The first83 candidate is the strongest tie shared most widely across modules; a84 weaker tie inside one class can wait.85867. Rule. **Label a module tie on the coupling ladder, tightest first:87 content, common, external, control, stamp, data.** Content reaches88 into another module's internals. Common shares global data. External89 follows a fixed outside format or protocol. Control passes a flag90 that steers the callee. Stamp passes a whole structure where a part91 is needed. Data passes only the values needed. Use the rungs as92 diagnostic labels, not as a score.93948. Rule. **Label what holds a class together on the cohesion ladder,95 weakest first: coincidental, logical, temporal, procedural,96 communicational, sequential, functional.** Coincidental has no97 theme. Logical groups by kind of thing. Temporal groups by when it98 runs. Procedural groups by a shared sequence. Communicational works99 on the same data. Sequential feeds one part's output to the next.100 Functional has every part serving one task. A class held together101 only by kind or by timing is a candidate to split.1021039. Rule. **Read package dependency counts as afferent, efferent and104 instability.** Afferent counts how many modules depend on this one.105 Efferent counts how many it depends on. Instability is106 `efferent / (afferent + efferent)`, from 0 for stable to 1 for107 unstable. Treat the counts as places to look, not as targets.10810910. Default. **Depend in the direction of stability.** A module many110 others depend on should not depend on volatile details. Point each111 dependency from the less stable module toward the more stable one.112113 The exception is a boundary adapter whose job is to meet a volatile114 outside system. Keep it at the edge and keep the stable core clear115 of it.11611711. Rule. **Measure before judging.** Evidence is what changes together118 in the version history, the size of the change a typical request119 causes, and dependency counts. A coupling smell becomes a finding120 only with such evidence; without it, the red flags below are places121 to look.122123## Pattern124125Before, `BillingDesk` calls `InvoiceBuilder.build(visit, "AXA", 2, true)`.126`"AXA"` is an insurer code that billing and claims must spell the same127way, `2` is the plan tier, and `true` means lab fees are included. The128call carries connascence of meaning, because the bare code and tier are129conventions, and connascence of position, because the caller must130remember which slot is which. The flag also steers the builder's logic,131which is control coupling.132133Before:134135```text136class BillingDesk137 - invoices: InvoiceBuilder138 + new(invoices: InvoiceBuilder)139 + invoice(visit: Visit): Invoice140 return invoices.build(visit, "AXA", 2, true)141142class InvoiceBuilder143 + build(visit: Visit, insurer: String, tier: Int, labFees: Boolean): Invoice144 return new Invoice(visit, insurer, tier, labFees)145```146147After, `InvoiceBuilder.build(visit, coverage)` takes one `Coverage`.148The insurer code is an `InsurerCode`, the tier is a `PlanTier`, and the149lab-fee choice is a `LabFees`. The three parts are named, so a caller150cannot put the tier where the insurer belongs, and the flag no longer151reaches the builder as a bare switch.152153After:154155```text156value InsurerCode157 - code: String158 + new(code: String)159160enum PlanTier161 Basic162 Family163164enum LabFees165 Excluded166 Included167168value Coverage169 - insurer: InsurerCode170 - tier: PlanTier171 - labFees: LabFees172 + new(insurer: InsurerCode, tier: PlanTier, labFees: LabFees)173174class BillingDesk175 - invoices: InvoiceBuilder176 + new(invoices: InvoiceBuilder)177 + invoice(visit: Visit, coverage: Coverage): Invoice178 return invoices.build(visit, coverage)179180class InvoiceBuilder181 + build(visit: Visit, coverage: Coverage): Invoice182 return new Invoice(visit, coverage)183```184185## Red flags186187Places to look, not verdicts. A red flag becomes a finding only with188evidence: a measurement, a reproducible bug, or a failing test.189190- A request that keeps touching the same set of files across different191 modules.192- A boolean or mode parameter that switches the callee's behaviour.193- A parameter list of several values of the same type whose order194 matters.195- A magic value that two modules must spell the same way.196- Two classes whose version history shows changes in the same commits.197- A module many others depend on that depends on a volatile detail.198199## Common mistakes200201- Treating a metric as a target and refactoring until the number moves.202- Trying to remove all coupling. Parts that work together must know203 something about each other; the goal is a weaker, more local tie.204- Counting imports and missing connascence of meaning, timing or205 algorithm that no import shows.206- Splitting a cohesive class only because it is long.207- Reading high instability as a defect. A leaf module with no dependants208 is meant to be unstable.209210## Related skills211212- [oo-design](../oo-design/SKILL.md) sizes the task and defines the213 rule labels.214- [oo-assigning-responsibilities](../oo-assigning-responsibilities/SKILL.md)215 decides where a new behaviour goes when the question is ownership,216 not coupling.217218## Further reading219220- [Connascence](references/connascence.md)221- [Coupling and cohesion ladders](references/coupling-and-cohesion-ladders.md)