Data Clumps

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

Data clumps

Loading interactive demo…

Fowler's Data Clumps: "bunches of data that hang around together ought to be made into their own object." The stage prints a small fixture program as signatures only, every class head, field, and method signature with the bodies left out, and the detector reads each signature, compares every pair, and keeps the names that travel together. The test for a clump is to delete one of the values: would the others still make sense? The refactor knob applies the scenario's Introduce Parameter Object steps one at a time and the detector reads the result. The refactoring is the library's own toy form: the new class is a bag of fields, and every caller wraps what it passed.Take the tour, or press and explore. Legend:

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

The pair of signatures being compared, the second one lit and the first one tinted.
A band on every signature that owns a clump; each clump has its own band tone, and the strip beneath the sheet shows the same tones.
The class the refactoring introduced.
A signature not yet read.

signatures counts the signatures read so far out of every method of every class, overlaps the pairs that share a name, clumps the shared sets of at least the size and what the original had, widest the most names any clump holds and how many signatures it spans, verdict data clumps or fine, line what the tapped line is. The gutter writes the shared count beside the second signature of a pair. Tap a line to read its names and the clump it belongs to.

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. Every method of every class contributes one signature: its parameter names. Every pair of signatures is compared once, and a pair that shares a name is an overlap. A shared set of at least size names, seen for the first time, is a clump, and every signature holding all of its names is an owner. The hotel reads four signatures, finds three overlaps, and one clump of three names across three owners.

Why names, not types. Three numbers in a row say nothing; it is the same three names in the same company that give the clump away. The detector matches names and carries the types along from the first owner, so start, nights, guests is one clump whether the hotel, the rate card, or the mailer declared it first.

Why the cure works. Introduce Parameter Object makes the names the fields of a new class, replaces them in every owner's signature with one object at the first clump position, reads start as stay.start in the bodies, and wraps what every caller passed in new Stay(...). The three signatures still overlap afterwards, on one name, stay, which is under the size, so the clump is gone. The canvas holds two clumps and needs two steps: a box across three signatures and a colour across two.

What the size means. The knob is the smallest group of names that counts; the detector is built with it. At three the library desk is clean, though title, author travel together through two signatures. At two that pair is a clump. Fowler offers no number, only the deletion test: whether title without author still makes sense is a judgement call, which is why the knob is yours.

The sibling smells. A long parameter list is often several clumps laid end to end, and the Long Method lesson's Extract Method is the move that usually exposes them, since a helper's signature is where the same names first show up twice.

What the stage does not show. The detector reads parameter clumps only; a clump of fields that always sit side by side is the same smell with Extract Class as its cure, and is not traced here. The refactoring is the library's toy form: the new class is a bag of fields with no methods, every receiver of a rewritten call has a type the model can tell, and a name typed two ways across the owners is refused rather than reconciled.

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

Signatures are read before any comparison. signatures walks every module, class, and method in declaration order and emits one signature per method, zero-parameter ones included, with its index and the total, so the stage can light the reading as its own pass.
Every pair once. The inner loop starts at i + 1, so each pair is compared in one direction, and the first signature of the pair is the one whose name order and types the clump keeps.
A clump is keyed by its sorted names. The seen set holds the sorted, joined shared names, so a second pair sharing the same set emits an overlap and no second clump; the names in the payload keep the first owner's order, not the sorted one.
Owners come from every signature, not the pair. Once a pair finds the set, owners filters all signatures for the ones holding every name, which is how a clump found between the hotel and the rate card also counts the mailer.
No subset suppression. The class comment says so: a subset of a clump that some other pair shares would be a clump of its own, so the fixtures keep their clumps disjoint, and the threshold is a constructor argument so the knob rebuilds the detector and nothing else.

A start day, a count of nights, and a count of guests are passed through three signatures in a row, and nobody has named the thing they make. Kent Beck and Martin Fowler listed Data Clumps among the code smells in 1999 with a test for spotting one: delete one of the values and ask whether the others still make sense. The cure is to give the bunch a class, Introduce Parameter Object when it travels through signatures and Extract Class when it sits in fields. This lesson reads every signature of a small program, finds the names that keep company, and then runs the cure.

1997Kent Beck - Smalltalk Best Practice Patterns catalogues the small habits of good Smalltalk code, Composed Method and Collecting Parameter among them; the refactoring catalogue that followed credits Beck for many of its moves.source
1999Martin Fowler, with Kent Beck - Refactoring: Improving the Design of Existing Code names Data Clumps in its catalogue of smells, with Introduce Parameter Object, Extract Class, and Preserve Whole Object as the cures.source
2003Eric Evans - Domain-Driven Design describes value objects, small objects defined by their attributes rather than an identity, which is what a clump becomes once it has a name.source
2018Martin Fowler - The second edition keeps Data Clumps and adds Combine Functions into Class, for the case where the functions that take the clump should move onto the new class too.source

Used today

IDE refactorings - IntelliJ, ReSharper, and Visual Studio offer Introduce Parameter Object as a menu item: pick the parameters, name the class, and every caller is rewritten.
API design - An options object in place of a tail of positional arguments is the same move at a library's edge; callers name what they pass instead of counting positions.
DTO cleanup - Transfer objects grow fields that always change together; splitting the bunch out gives it a type and one place for its checks.

Did you know

Fowler's test for a clump is to delete one of the values: if the rest no longer make sense, the bunch is an object waiting to be born.source
Long Parameter List is the sibling smell: a signature that grew by handing over every value a method might need. A clump is the part of such a list that several methods share, which is why one parameter object here shortens three signatures at once.source
Primitive Obsession is the smell next door: a phone number kept as a string, money as a float. A clump of primitives and a lone primitive standing in for a type end the same way, with a small class.source
Introduce Parameter Object has its own page in Fowler's online catalogue, with the mechanics: create the class, add a parameter for it, pass the object, then replace each element in turn.source

program

refactororiginal

size3 names

signatures: 4
overlaps: 3
clumps: 1
widest: 3 names across 3 signatures
verdict: data clumps
line: class Hotel: 2 fields, 1 method

data-clumps.ts

import type { Program } from "./program";import type { Tracer } from "../trace";import type { SmellDetector } from "./detector";/** A group of parameter names that travel together through more than one signature. */export interface Clump {  readonly id: number;  /** The names, in the order the first owner declares them. */  readonly names: readonly string[];  /** The declared type of each name, from the first owner. */  readonly types: readonly string[];  /** Every method whose signature holds all the names: "Hotel.reserve". */  readonly owners: readonly string[];  /** How many owners: the number of signatures the clump is spread over. */  readonly count: number;}export interface ClumpReport {  /** Signatures examined: every method of every class. */  readonly signatures: number;  readonly clumps: readonly Clump[];  /** The most names any clump holds; 0 when there is none. */  readonly largest: number;  readonly smelly: boolean;}/** One method's parameter list, as the detector sees it. */interface Signature {  readonly owner: string;  readonly className: string;  readonly method: string;  readonly names: readonly string[];  readonly types: ReadonlyMap<string, string>;}/** * Fowler's Data Clumps, in parameter form: the same few names that * always appear together in signatures (`start, nights, guests`) and * want to be one object. Every method of every class contributes its * signature; every pair of signatures with a shared name is an * `overlap`; a shared set of at least `minSize` names, seen for the * first time, is a `clump` owned by every signature that holds all of * its names. A subset of a clump that some other pair shares would be a * clump of its own: there is no suppression, so fixtures keep their * clumps disjoint. Field clumps are out of scope here; the cure for a * parameter clump is Introduce Parameter Object. * * Time: O(s² · p) over s signatures of at most p parameters. */export class DataClumps implements SmellDetector<Program, ClumpReport> {  constructor(    readonly minSize = 3,    private readonly tracer?: Tracer,  ) {}  analyze(program: Program): ClumpReport {    const signatures = this.signatures(program);    signatures.forEach((signature, index) => {      // ▸ one method's parameter names, read from its class      this.tracer?.emit("signature", { className: signature.className, method: signature.method, params: signature.names.map((n) => `${n}: ${signature.types.get(n)}`), index, count: signatures.length });    });    const clumps: Clump[] = [];    const seen = new Set<string>();    for (let i = 0; i < signatures.length; i++) {      for (let j = i + 1; j < signatures.length; j++) {        const a = signatures[i]!;        const b = signatures[j]!;        const shared = a.names.filter((n) => b.names.includes(n));        if (shared.length === 0) continue;        // ▸ two signatures share at least one name        this.tracer?.emit("overlap", { a: a.owner, b: b.owner, shared, size: shared.length });        const key = [...shared].sort().join(",");        if (shared.length < this.minSize || seen.has(key)) continue;        seen.add(key);        const owners = signatures.filter((s) => shared.every((n) => s.names.includes(n))).map((s) => s.owner);        const clump: Clump = { id: clumps.length, names: shared, types: shared.map((n) => a.types.get(n)!), owners, count: owners.length };        clumps.push(clump);        // ▸ a shared set big enough and new: a clump, owned by every signature holding all of it        this.tracer?.emit("clump", { id: clump.id, names: clump.names, types: clump.types, owners: clump.owners, count: clump.count });      }    }    const largest = clumps.reduce((max, c) => Math.max(max, c.names.length), 0);    const smelly = clumps.length > 0;    // ▸ the clumps found, against the smallest size that counts    this.tracer?.emit("verdict", { signatures: signatures.length, clumps: clumps.length, largest, minSize: this.minSize, smelly });    return { signatures: signatures.length, clumps, largest, smelly };  }  /** Every method of every class in declaration order, with its parameter names and their types. */  private signatures(program: Program): readonly Signature[] {    const out: Signature[] = [];    for (const module of program.modules) {      for (const cls of module.classes) {        for (const method of cls.methods) {          out.push({ owner: `${cls.name}.${method.name}`, className: cls.name, method: method.name, names: method.params.map((p) => p.name), types: new Map(method.params.map((p) => [p.name, p.type] as const)) });        }      }    }    return out;  }}

clumps =: 1
largest =: 3

1 clump across 4 classs; the widest holds 3 names. Still data clumps.

import type { Program } from "./program";import type { Tracer } from "../trace";import type { SmellDetector } from "./detector";/** A group of parameter names that travel together through more than one signature. */export interface Clump { readonly id: number; /** The names, in the order the first owner declares them. */ readonly names: readonly string[]; /** The declared type of each name, from the first owner. */ readonly types: readonly string[]; /** Every method whose signature holds all the names: "Hotel.reserve". */ readonly owners: readonly string[]; /** How many owners: the number of signatures the clump is spread over. */ readonly count: number;}export interface ClumpReport { /** Signatures examined: every method of every class. */ readonly signatures: number; readonly clumps: readonly Clump[]; /** The most names any clump holds; 0 when there is none. */ readonly largest: number; readonly smelly: boolean;}/** One method's parameter list, as the detector sees it. */interface Signature { readonly owner: string; readonly className: string; readonly method: string; readonly names: readonly string[]; readonly types: ReadonlyMap<string, string>;}/** * Fowler's Data Clumps, in parameter form: the same few names that * always appear together in signatures (`start, nights, guests`) and * want to be one object. Every method of every class contributes its * signature; every pair of signatures with a shared name is an * `overlap`; a shared set of at least `minSize` names, seen for the * first time, is a `clump` owned by every signature that holds all of * its names. A subset of a clump that some other pair shares would be a * clump of its own: there is no suppression, so fixtures keep their * clumps disjoint. Field clumps are out of scope here; the cure for a * parameter clump is Introduce Parameter Object. * * Time: O(s² · p) over s signatures of at most p parameters. */export class DataClumps implements SmellDetector<Program, ClumpReport> { constructor( readonly minSize = 3, private readonly tracer?: Tracer, ) {} analyze(program: Program): ClumpReport { const signatures = this.signatures(program); signatures.forEach((signature, index) => { // ▸ one method's parameter names, read from its class this.tracer?.emit("signature", { className: signature.className, method: signature.method, params: signature.names.map((n) => `${n}: ${signature.types.get(n)}`), index, count: signatures.length }); }); const clumps: Clump[] = []; const seen = new Set<string>(); for (let i = 0; i < signatures.length; i++) { for (let j = i + 1; j < signatures.length; j++) { const a = signatures[i]!; const b = signatures[j]!; const shared = a.names.filter((n) => b.names.includes(n)); if (shared.length === 0) continue; // ▸ two signatures share at least one name this.tracer?.emit("overlap", { a: a.owner, b: b.owner, shared, size: shared.length }); const key = [...shared].sort().join(","); if (shared.length < this.minSize || seen.has(key)) continue; seen.add(key); const owners = signatures.filter((s) => shared.every((n) => s.names.includes(n))).map((s) => s.owner); const clump: Clump = { id: clumps.length, names: shared, types: shared.map((n) => a.types.get(n)!), owners, count: owners.length }; clumps.push(clump); // ▸ a shared set big enough and new: a clump, owned by every signature holding all of it this.tracer?.emit("clump", { id: clump.id, names: clump.names, types: clump.types, owners: clump.owners, count: clump.count }); } } const largest = clumps.reduce((max, c) => Math.max(max, c.names.length), 0); const smelly = clumps.length > 0; // ▸ the clumps found, against the smallest size that counts this.tracer?.emit("verdict", { signatures: signatures.length, clumps: clumps.length, largest, minSize: this.minSize, smelly }); return { signatures: signatures.length, clumps, largest, smelly }; } /** Every method of every class in declaration order, with its parameter names and their types. */ private signatures(program: Program): readonly Signature[] { const out: Signature[] = []; for (const module of program.modules) { for (const cls of module.classes) { for (const method of cls.methods) { out.push({ owner: `${cls.name}.${method.name}`, className: cls.name, method: method.name, names: method.params.map((p) => p.name), types: new Map(method.params.map((p) => [p.name, p.type] as const)) }); } } } return out; }}