Main idea

An exception named CancelledItemNotEditable isn't an error message: it is a business rule written in code, readable by a support agent who doesn't program. An exception named InvalidStateException says the same thing to the processor and nothing to anyone else. It is that gap, and not the technical quality of the repository, that decides whether a product question can find its answer there.

The condition runs through the whole material: entities carrying the names users actually use, actions whose labels can be read, events that tell what happened, policies that make cascading reactions visible, modules with a predictable structure. A repository where the domain concepts are hidden behind technical names and the rules are scattered stays opaque, however carefully it is split up or covered by tests.

The requirement is an old one — domain-driven design approaches have carried it for a long time — and it wasn't created by the arrival of assistants. A developer picking up such a repository pays the same permanent translation between the business need and the software mechanics; every change requires rebuilding that link, every search for a rule costs more. What being able to query the code changes is that the flaw becomes measurable from outside the technical team: it no longer shows up as diffuse slowness, but as answers nobody can obtain.

Why it matters

This shifts the criterion applied before installing a querying system. The question to ask of a repository isn't "is it well kept?" but "is the vocabulary of the domain written into it?" — two properties that often occur together and have no necessary connection.

It also gives a non-technical argument for an investment that only had a technical one. Renaming concepts toward the language of the business stops being a craftsman's preference the moment support, pre-sales and product management depend on it to get answers.

Nuances and limits

Uniformity doesn't exist: one and the same repository speaks business in the billing module, written twenty years earlier by people who knew the domain, and stays mute in the integration layer. The condition is checked zone by zone, not across the whole repository.

The vocabulary written into the code is also dated. An entity name that has survived three repositionings tells of a business nobody practises any more, and its very readability makes it misleading.

Finally, a correct business name can cover a wrong rule. That an exception expresses a rule makes the rule readable, not accurate: what becomes queryable is the code, not the intended product.

Open questions

• Who arbitrates the vocabulary when users call an object something other than the code does, and both usages have their champions inside the company?
• How, before committing to the work, do you measure the gap between a repository's vocabulary and the domain's?