In Domain-Driven Design, what is an 'intention-revealing interface' for a class or method, and why does a name like isOverdue() help more than a name like checkFlag() when other developers need to keep changing the code?

## What the discipline is An **intention-revealing interface** is a naming discipline applied to classes, methods, and parameters: pick names that describe the **effect and purpose** of an operation in the vocabulary of the domain, not the mechanics of how it's implemented. Concretely, this means asking 'if a new developer sees only this method's signature and a one-line doc comment, can they use it correctly without opening the body?' A method named `isOverdue()` passes that test; one named `checkFlag()` or `process()` fails it, because the caller has to read the source to know what 'checking' or 'processing' actually produces or changes. The same test applies to: - **constructors and factory methods** -- `Money.dollars(100)` versus `new Money(100, 0)` - **boolean parameters** -- avoid unlabeled flags like `save(true)`; prefer an enum or two named methods - **return types** -- returning a well-named domain type instead of an unlabeled boolean when the meaning isn't self-evident from the name alone ## Why the discipline exists This practice exists because Domain-Driven Design treats the code itself as an expression of the **'ubiquitous language'** -- the shared vocabulary domain experts and developers use so a conversation about the business maps directly onto class and method names in the code. When names leak implementation detail instead of expressing intent, two costs compound: 1. Domain experts can no longer read the code (or its tests) as a description of the rules they care about. 2. Developers modifying the internals have to worry that some caller depends on an implementation detail the name never promised. Intention-revealing interfaces are what let you change the inside of a method freely -- that's the entire point of **supple design**, a model that stays easy to reshape as understanding deepens -- because callers only ever depended on the contract implied by the name, not on how it's computed. ## What it costs The cost is real: - Good names take longer to find than lazy ones, and as the team's understanding of the domain deepens, a name that seemed accurate six months ago can become misleading, which means renaming -- and renaming has a blast radius across every caller. - Modern IDE refactoring tools make project-wide renames close to free for well-encapsulated code, but the discipline of actually doing the rename (rather than leaving a stale, confusing name in place because 'it's used everywhere') is a **cultural cost**, not just a technical one. - There's also a tension with brevity: chasing maximal descriptiveness can produce names so long they hurt readability at call sites, so in practice teams balance precision against a name that still reads naturally in context, often relying on the surrounding class or namespace to carry some of the meaning so the method itself can stay short. ## How it shows up in production code In production code, the anti-pattern shows up as generically named classes (`OrderManager`, `DataUtil`, `Helper`) that become dumping grounds for unrelated logic because nothing about the name constrains what belongs there, and as methods whose name describes an algorithm rather than an outcome. - A subtler and more dangerous failure is a name that's technically accurate but incomplete -- a `save()` method that also sends a notification email as a side effect no caller expects, discovered only when a test environment starts spamming real customers. - Boolean control-flag parameters are a recurring source of production incidents: a call site like `shipOrder(order, true)` reads fine to the author but is opaque six months later to anyone who has to guess what `true` means without opening the method. ## The Money illustration A concrete illustration is Eric Evans's own Money example in Domain-Driven Design: instead of exposing a raw numeric field and letting callers do arithmetic and rounding themselves, scattering tax-rounding logic across the codebase, the `Money` type exposes methods like `add(Money): Money` and `applyTax(Percentage): Money`. Every call site reads as a domain statement, the rounding and currency rules live in exactly one place, and if the rounding policy changes, no caller needs to change at all. That single naming and encapsulation choice is what makes the rest of supple design's tools -- side-effect-free functions, closure of operations, assertions -- effective: they all assume the interface already tells the truth about what's happening, so a reader trusts the name enough to build on it without re-verifying it every time.