Message Chains

in reviewThis lesson is complete and being validated before release - details may still change.

Message chains

Loading interactive demo…

A class from a small fixture program, printed on the stage, and Fowler's Message Chains smell read off it: a client asks one object for another object, which the client then asks for yet another object, the train wreck a.b().c().d(). The detector reads every spine of fields and calls from its root outward and counts the hops that reach past the first object, the strangers of the Law of Demeter; a spine with enough of them is a chain. The refactor knob applies the scenario's Hide Delegate steps one at a time and the detector reads the class again. The refactorings are the library's own toy forms: the new method lands on another class, so the sheet shows only the shorter route.Take the tour, or press and explore. Legend:

The panel beside the stage is the real MessageChains class from the published library executing in your browser, with the current line highlighted.

The statement whose spine is being read; the strip below lists its hops root outward, the hop in hand ringed.
A statement holding a chain: a spine over the limit.
A statement whose spines all stayed under the limit, once its method's verdict is in.
Lines of a method the detector has not reached yet.

spines counts the spines of two or more hops read so far, longest the most stranger hops any spine reached and what the original had, chains the spines at or over the limit and what the original had, verdict the class against the limit, line the tapped line's longest spine and its strangers. The gutter writes the stranger count beside each statement as it is read. Tap a line to read its longest spine.

The code panel shows bare executable code by default. The bar above it names the file (hover the name for the full published path); options holds the toggles: comments, the tracer instrumentation that produces this visualization, and verbose names for the terse identifiers (display only: the default is the byte-exact published file). The view switch adds plain-English narration: both interleaves it with the code, pseudo shows only the pseudocode. hide code collapses the panel; the rail it leaves behind brings it back.

Keys: Space play/pause · ←/→ step · Home/End jump · R reset · F fullscreen · G guided tour

What the detector counts. A spine is a run of fields and calls down to one root: order.customer.address.zip is four hops from the root order. A hop is a stranger hop when it is read off something the method was never handed, a call's result or a field of an object other than this. The first hop off a parameter is a friend; the second reaches past it, so the shipping label's spine is two strangers out. The Law of Demeter lesson draws the line between friends and strangers; this one counts how far past the line a spine goes.

Why the limit is a count. One stranger hop is everywhere and mostly harmless: order.items.length asks a collaborator a simple question. Two is the train wreck, a.b().c().d(): the caller now knows that an order has a customer and that a customer has an address, and a change to either breaks it. The limit knob is that count; the detector reads the same spines at every setting and only which of them count as chains moves.

Why Hide Delegate works one hop at a time. The class at the start of the route gains a method that does the next hop on the caller's behalf: Order gets shipTo(), which returns this.customer.address, and order.customer.address.zip becomes order.shipTo().zip. The route is the same length; the caller just sees one hop less of it. Every chain through that hop shortens together, which is why one step clears both of the shipping label's chains, while the clinic's four-object reach needs two.

The alternative. When the end of the chain is used in one place, Fowler's other cure is to extract the use into a method and move it down the chain to the object that owns the data. Hide Delegate keeps the caller; Move Method moves the work.

What the stage does not show. The refactorings here are the library's toy form: Hide Delegate adds one method on one class and rewrites every spine of that shape in the program, and the new method lives on a class the sheet does not print. Real tools let you name the method, pick which callers to rewrite, and forward arguments through; the counting is the same.

Choices worth reading closely in the implementation (the code panel's comments and tracer checkboxes reveal the full published file):

A spine is read down, then measured up. read follows each field or call's target down to the root and lists the hops back in root-outward order, so the trace and the strip both walk the way a reader does, from the object the method was handed.
A stranger is a property of the hop's target. measure asks one question per hop: is the target a call, or a field of anything but this? The answer does not depend on where the spine ends, so this.rates.lookup(x) reads as two friends and order.items.length as one friend and one stranger.
Call arguments are spines of their own. A chain hidden inside an argument, like the country passed to lookup, is found by recursing into each hop's arguments after the outer spine is measured, outermost first.
One-hop spines stay silent. measure returns before emitting anything for a spine of one hop, so the trace carries only what could ever be a chain and a control class produces a short run.
The limit is a constructor argument. The knob rebuilds the detector; hop events are identical at every setting, and only whether chain fires and the verdict's payload change.

The rule came before the smell. In 1988 Karl Lieberherr's group at Northeastern, working on the Demeter system, wrote down the Law of Demeter: a method should only talk to its own fields, its parameters, and the objects it makes. A decade later Kent Beck and Martin Fowler catalogued the shape that breaks it, a client asking one object for another object which it then asks for yet another, and named it Message Chains, with Hide Delegate as the cure. This lesson reads the chains off a small program, counts how far each one reaches past the first object, and hides one delegate at a time.

1988Karl Lieberherr, Ian Holland, and Arthur Riel - 'Object-Oriented Programming: An Objective Sense of Style' at OOPSLA states the Law of Demeter: a method sends messages only to itself, its arguments, its own fields, and the objects it creates.source
1999Martin Fowler, with Kent Beck - Refactoring: Improving the Design of Existing Code lists Message Chains among the code smells, with Hide Delegate as the cure and Extract Method and Move Method as the alternative when the chain's end is used in one place.source
1999Andrew Hunt and David Thomas - The Pragmatic Programmer turns the law into a tip, 'Minimize Coupling Between Modules', and the folk rule 'don't talk to strangers': a method should not reach through one object to call a method on another.source
2018Martin Fowler - The second edition keeps Message Chains and its mirror image Middle Man: a class that hides so much that every one of its methods only delegates, which is where too much Hide Delegate leads.source

Used today

Lint rules - Static analysers ship a Law of Demeter rule that flags member access chained past a method's own fields and parameters, PMD's among the oldest.
API design - A fluent interface is a chain on purpose: every call returns the same object or a builder, so the client never reaches into a stranger.
Code review - A long run of dots in a diff is the quickest sign that a caller knows the route between classes it should not know about.

Did you know

Middle Man is the mirror smell: hide every delegate and a class ends up with methods that do nothing but forward, at which point Fowler's advice is Remove Middle Man and let the caller talk to the delegate again.source
A fluent builder like new Query().from(a).where(b).limit(c) is a chain the smell does not mind: each call returns the same object, so the client is still talking to one friend, not reaching through it to a stranger.source
The folk form of the Law of Demeter is 'use only one dot', which over-counts: this.rates.lookup(x) has two dots and no stranger, since a method's own field is a friend.source
The phrase 'train wreck' for a.b().c().d() is the heading Robert Martin gives the smell in Clean Code, where the fix is to ask the first object for what the caller actually wants.source

class

refactororiginal

limit2 strangers

spines: 4
longest: 2 strangers
chains: 2
verdict: message chains
line: no spine

message-chains.ts

import type { ClassDecl, Expr, Method } from "./program";import type { Tracer } from "../trace";import { CodePrinter } from "./code-printer";import type { SmellDetector } from "./detector";import { ProgramQuery } from "./program-query";/** One member access along a spine, root outward: `customer` in `order.customer.address`. */export interface ChainHop {  readonly member: string;  readonly kind: "field" | "call";  /** The hop reaches past the first object: its target is a call's result or a field of something other than `this`. */  readonly stranger: boolean;  /** The printed expression the hop is applied to. */  readonly target: string;}/** A spine whose stranger hops reach the limit: Fowler's message chain, the "train wreck" `a.b().c().d()`. */export interface MessageChain {  /** The statement the chain sits in. */  readonly nodeId: string;  /** The printed spine. */  readonly text: string;  /** The printed root: `this`, a name, a `new`, or a literal. */  readonly root: string;  readonly hops: readonly ChainHop[];  /** The stranger hops: how far past the first object the spine reaches. */  readonly length: number;}export interface ChainReport {  readonly method: string;  readonly chains: readonly MessageChain[];  /** The most stranger hops any spine in the method has; 0 when none reaches past one object. */  readonly longest: number;  /** At least one chain. */  readonly smelly: boolean;}/** A spine while it is read: the root and the hops from it outward, with the statement it belongs to. */interface Spine {  readonly nodeId: string;  readonly root: Expr;  readonly hops: readonly SpineHop[];  readonly expr: Expr;}interface SpineHop {  readonly member: string;  readonly kind: "field" | "call";  readonly target: Expr;  /** A call's arguments; empty for a field. */  readonly args: readonly Expr[];}interface Tally {  readonly chains: MessageChain[];  longest: number;}/** * Fowler's Message Chains smell, read purely from syntax. A spine is a * maximal nest of field accesses and calls down to a root (`this`, a * name, a `new`, a literal); its hops run from the root outward. A hop * is a stranger hop when it reaches past the first object: its target is * a call's result, or a field of something other than `this`. So * `order.items.length` has one stranger hop, `this.a.b().c` has one, and * `order.customer.address.zip` has two: the "train wreck" that couples * the caller to the whole route between the objects. A spine whose * stranger hops reach `limit` is a chain; Hide Delegate shortens it one * hop at a time. Call arguments along a spine are spines of their own. * * Time: O(n) over the method's expression nodes. Space: O(depth). */export class MessageChains implements SmellDetector<Method, ChainReport> {  private readonly printer = new CodePrinter();  constructor(    readonly limit = 2,    private readonly tracer?: Tracer,  ) {}  analyze(method: Method): ChainReport {    return this.run(method, 0, 1);  }  /** Every method of the class in declaration order, so one trace walks the whole class. */  analyzeClass(cls: ClassDecl): readonly ChainReport[] {    return cls.methods.map((method, index) => this.run(method, index, cls.methods.length));  }  private run(method: Method, index: number, count: number): ChainReport {    const tally: Tally = { chains: [], longest: 0 };    // ▸ a method begins: no chains, no strangers yet    this.tracer?.emit("method", { name: method.name, index, count });    ProgramQuery.walk(method.body, (stmt) => {      for (const expr of ProgramQuery.exprs(stmt)) this.spines(expr, stmt.id, method.name, tally);    });    const smelly = tally.chains.length > 0;    // ▸ the method's chains and its longest spine against the limit    this.tracer?.emit("verdict", { name: method.name, chains: tally.chains.length, longest: tally.longest, limit: this.limit, smelly });    return { method: method.name, chains: tally.chains, longest: tally.longest, smelly };  }  /** Every spine under an expression, outermost first, each read once; the parts beside a spine are searched for spines of their own. */  private spines(expr: Expr, nodeId: string, method: string, tally: Tally): void {    switch (expr.kind) {      case "field":      case "call": {        const spine = this.read(expr, nodeId);        this.measure(spine, method, tally);        for (const hop of spine.hops) for (const arg of hop.args) this.spines(arg, nodeId, method, tally);        this.beside(spine.root, nodeId, method, tally);        return;      }      default:        this.beside(expr, nodeId, method, tally);    }  }  /** The spines inside a root or a non-member expression: a `new`'s arguments, an operator's operands. */  private beside(expr: Expr, nodeId: string, method: string, tally: Tally): void {    switch (expr.kind) {      case "new":        for (const arg of expr.args) this.spines(arg, nodeId, method, tally);        return;      case "unary":        this.spines(expr.operand, nodeId, method, tally);        return;      case "binary":        this.spines(expr.left, nodeId, method, tally);        this.spines(expr.right, nodeId, method, tally);        return;      default:        return;    }  }  /** Follows the targets down to the root and lists the hops back up, root outward. */  private read(expr: Expr, nodeId: string): Spine {    const hops: SpineHop[] = [];    let current = expr;    while (current.kind === "field" || current.kind === "call") {      hops.unshift(current.kind === "field" ? { member: current.name, kind: "field", target: current.target, args: [] } : { member: current.method, kind: "call", target: current.target, args: current.args });      current = current.target;    }    return { nodeId, root: current, hops, expr };  }  /** Counts the stranger hops of a spine; one-hop spines stay silent, every longer spine is traced hop by hop. */  private measure(spine: Spine, method: string, tally: Tally): void {    if (spine.hops.length < 2) return;    const hops: ChainHop[] = [];    let strangers = 0;    spine.hops.forEach((hop, index) => {      const stranger = hop.target.kind === "call" || (hop.target.kind === "field" && hop.target.target.kind !== "this");      if (stranger) strangers++;      const target = this.printer.expr(hop.target);      hops.push({ member: hop.member, kind: hop.kind, stranger, target });      // ▸ one hop along a spine, root outward; a stranger when it reaches past the first object      this.tracer?.emit("hop", { nodeId: spine.nodeId, method, index, member: hop.member, kind: hop.kind, target, stranger, strangers });    });    tally.longest = Math.max(tally.longest, strangers);    if (strangers < this.limit) return;    const chain: MessageChain = { nodeId: spine.nodeId, text: this.printer.expr(spine.expr), root: this.printer.expr(spine.root), hops, length: strangers };    tally.chains.push(chain);    // ▸ the spine's strangers reach the limit: a message chain    this.tracer?.emit("chain", { nodeId: spine.nodeId, method, text: chain.text, root: chain.root, hops: hops.map((h) => h.member), strangers, count: tally.chains.length });  }}

chains =: 2
longest =: 2

The class: 2 chains; the longest spine 2 strangers. Still message chains.

import type { ClassDecl, Expr, Method } from "./program";import type { Tracer } from "../trace";import { CodePrinter } from "./code-printer";import type { SmellDetector } from "./detector";import { ProgramQuery } from "./program-query";/** One member access along a spine, root outward: `customer` in `order.customer.address`. */export interface ChainHop { readonly member: string; readonly kind: "field" | "call"; /** The hop reaches past the first object: its target is a call's result or a field of something other than `this`. */ readonly stranger: boolean; /** The printed expression the hop is applied to. */ readonly target: string;}/** A spine whose stranger hops reach the limit: Fowler's message chain, the "train wreck" `a.b().c().d()`. */export interface MessageChain { /** The statement the chain sits in. */ readonly nodeId: string; /** The printed spine. */ readonly text: string; /** The printed root: `this`, a name, a `new`, or a literal. */ readonly root: string; readonly hops: readonly ChainHop[]; /** The stranger hops: how far past the first object the spine reaches. */ readonly length: number;}export interface ChainReport { readonly method: string; readonly chains: readonly MessageChain[]; /** The most stranger hops any spine in the method has; 0 when none reaches past one object. */ readonly longest: number; /** At least one chain. */ readonly smelly: boolean;}/** A spine while it is read: the root and the hops from it outward, with the statement it belongs to. */interface Spine { readonly nodeId: string; readonly root: Expr; readonly hops: readonly SpineHop[]; readonly expr: Expr;}interface SpineHop { readonly member: string; readonly kind: "field" | "call"; readonly target: Expr; /** A call's arguments; empty for a field. */ readonly args: readonly Expr[];}interface Tally { readonly chains: MessageChain[]; longest: number;}/** * Fowler's Message Chains smell, read purely from syntax. A spine is a * maximal nest of field accesses and calls down to a root (`this`, a * name, a `new`, a literal); its hops run from the root outward. A hop * is a stranger hop when it reaches past the first object: its target is * a call's result, or a field of something other than `this`. So * `order.items.length` has one stranger hop, `this.a.b().c` has one, and * `order.customer.address.zip` has two: the "train wreck" that couples * the caller to the whole route between the objects. A spine whose * stranger hops reach `limit` is a chain; Hide Delegate shortens it one * hop at a time. Call arguments along a spine are spines of their own. * * Time: O(n) over the method's expression nodes. Space: O(depth). */export class MessageChains implements SmellDetector<Method, ChainReport> { private readonly printer = new CodePrinter(); constructor( readonly limit = 2, private readonly tracer?: Tracer, ) {} analyze(method: Method): ChainReport { return this.run(method, 0, 1); } /** Every method of the class in declaration order, so one trace walks the whole class. */ analyzeClass(cls: ClassDecl): readonly ChainReport[] { return cls.methods.map((method, index) => this.run(method, index, cls.methods.length)); } private run(method: Method, index: number, count: number): ChainReport { const tally: Tally = { chains: [], longest: 0 }; // ▸ a method begins: no chains, no strangers yet this.tracer?.emit("method", { name: method.name, index, count }); ProgramQuery.walk(method.body, (stmt) => { for (const expr of ProgramQuery.exprs(stmt)) this.spines(expr, stmt.id, method.name, tally); }); const smelly = tally.chains.length > 0; // ▸ the method's chains and its longest spine against the limit this.tracer?.emit("verdict", { name: method.name, chains: tally.chains.length, longest: tally.longest, limit: this.limit, smelly }); return { method: method.name, chains: tally.chains, longest: tally.longest, smelly }; } /** Every spine under an expression, outermost first, each read once; the parts beside a spine are searched for spines of their own. */ private spines(expr: Expr, nodeId: string, method: string, tally: Tally): void { switch (expr.kind) { case "field": case "call": { const spine = this.read(expr, nodeId); this.measure(spine, method, tally); for (const hop of spine.hops) for (const arg of hop.args) this.spines(arg, nodeId, method, tally); this.beside(spine.root, nodeId, method, tally); return; } default: this.beside(expr, nodeId, method, tally); } } /** The spines inside a root or a non-member expression: a `new`'s arguments, an operator's operands. */ private beside(expr: Expr, nodeId: string, method: string, tally: Tally): void { switch (expr.kind) { case "new": for (const arg of expr.args) this.spines(arg, nodeId, method, tally); return; case "unary": this.spines(expr.operand, nodeId, method, tally); return; case "binary": this.spines(expr.left, nodeId, method, tally); this.spines(expr.right, nodeId, method, tally); return; default: return; } } /** Follows the targets down to the root and lists the hops back up, root outward. */ private read(expr: Expr, nodeId: string): Spine { const hops: SpineHop[] = []; let current = expr; while (current.kind === "field" || current.kind === "call") { hops.unshift(current.kind === "field" ? { member: current.name, kind: "field", target: current.target, args: [] } : { member: current.method, kind: "call", target: current.target, args: current.args }); current = current.target; } return { nodeId, root: current, hops, expr }; } /** Counts the stranger hops of a spine; one-hop spines stay silent, every longer spine is traced hop by hop. */ private measure(spine: Spine, method: string, tally: Tally): void { if (spine.hops.length < 2) return; const hops: ChainHop[] = []; let strangers = 0; spine.hops.forEach((hop, index) => { const stranger = hop.target.kind === "call" || (hop.target.kind === "field" && hop.target.target.kind !== "this"); if (stranger) strangers++; const target = this.printer.expr(hop.target); hops.push({ member: hop.member, kind: hop.kind, stranger, target }); // ▸ one hop along a spine, root outward; a stranger when it reaches past the first object this.tracer?.emit("hop", { nodeId: spine.nodeId, method, index, member: hop.member, kind: hop.kind, target, stranger, strangers }); }); tally.longest = Math.max(tally.longest, strangers); if (strangers < this.limit) return; const chain: MessageChain = { nodeId: spine.nodeId, text: this.printer.expr(spine.expr), root: this.printer.expr(spine.root), hops, length: strangers }; tally.chains.push(chain); // ▸ the spine's strangers reach the limit: a message chain this.tracer?.emit("chain", { nodeId: spine.nodeId, method, text: chain.text, root: chain.root, hops: hops.map((h) => h.member), strangers, count: tally.chains.length }); }}