In a design review, which signals say a proposed domain notation will not repay its cost?
answer
- audience before syntax
- count authors, not characters
- a helper function removes that too
- one-for-one rename adds no constraint
- control flow means you owe a toolchain
basics
~20 sThe notation does not repay when its authors are the people who wrote it, when its whole gain is punctuation an ordinary helper would remove, when its words are a one-for-one rename of existing members, or when it has begun growing its own control flow.
solid answer
~40 sI look at the audience first: if the only authors are the engineers who already read the plain API, there is no comprehension gap to close and the notation is a second surface serving nobody new. Then at the gain: if it removes repetition an ordinary helper or preset function would remove, take the function — it costs no vocabulary. Then at the shape: words that map one-for-one onto existing members add names without adding a constraint, and a notation that has grown its own conditional and its own loop has become a small language whose debugging, profiling and refactoring you now owe. Finally at ownership: one author who can safely change it is a bus-factor problem, not a platform.
code
pseudocode · 7 lines// notation: a new word for one existing call
rules {
require field "email" matches EMAIL
}
// helper function: same repetition removed, no new vocabulary
rules.add(matchRule("email", EMAIL))go deeper
Recall the cheapest alternative: a plain helper or preset function removes repetition without inventing words anyone has to learn. Reach for it before reaching for a notation.
Be able to list the ongoing costs a notation adds — translation layer, reference page, teaching, error messages, compatibility — and name the signals that say none of them will be repaid.
Argue it with evidence: who authors, how often, how often they were wrong, and what a preset function would have fixed instead. Say clearly what would change your mind.
Own the standard for the organisation: when a team may introduce a vocabulary other teams must learn, what it must ship alongside it, and how a notation that stops paying is retired.
## What the review is actually deciding A proposal to replace a plain configuration API with a notation is not a syntax preference. It is a proposal to create and staff a **second surface**: a vocabulary to teach, a reference to maintain, a translation layer to test, and a compatibility story for configurations written against last quarter's words. The question in the room is not "does this read nicer" — it usually does, in the slide. The question is whether anyone is better off often enough to repay that staffing. ## Signals that it will not repay 1. **An audience of one.** The people who will write the notation are the same people who wrote it and already read the API underneath. There is no comprehension gap being closed, only a dialect being introduced. 2. **The gain is punctuation.** The notation removes a few characters and one level of nesting from a call. An ordinary helper function, or a named preset for the three configurations actually used, removes the same repetition with no new vocabulary and no new reference page. 3. **One-for-one vocabulary.** Every word of the notation names exactly one existing member. A rename adds names without adding a constraint: nothing that was expressible before is now impossible, so the notation cannot prevent a single mistake. 4. **It has grown control flow.** Once the notation has its own conditional, its own loop or its own variables, the configurations written in it are programs — and programs need what the host already supplies for free: stepping, breakpoints, stack traces, profiling, refactoring, and a way to test a fragment in isolation. 5. **Nobody can safely change it.** The translation layer is understood by its author alone, and a change to the vocabulary requires reasoning about the machinery underneath. That is a bus factor, and it usually surfaces the first time the author is on leave. 6. **Nothing is measured.** The proposal argues from a single before-and-after slide rather than from how often configurations are written, by whom, and how often they were wrong. ## The costs to write on the board | Cost | Paid once | Paid forever | |---|---|---| | The translation layer from words to the API | design and implementation | tests, and a change whenever the API changes | | The vocabulary reference | first version | one edit per word ever added or renamed | | Teaching | first rollout | every new joiner, and every team that adopts it | | Error quality | the first good messages | messages for each new failure shape | | Compatibility | the first vocabulary | every configuration already written against older words | The left column is what proposals estimate. The right column is what they usually omit, and it is the column that decides. ## What to propose instead - **Named presets.** Most configuration surfaces are used in three or four shapes. Publish those as named functions and most of the verbosity disappears with no new vocabulary. - **A smaller API.** Verbosity is often a symptom of a surface that exposes knobs nobody sets. Removing them is cheaper than wrapping them. - **Better types on the existing members.** If the complaint is that mistakes happen, a distinct type for a quantity that was being passed as a bare number prevents more errors than a notation that accepts the same bare number in nicer clothing. - **One block, not a language.** If a notation really is wanted, cap it: a flat vocabulary, no control flow, no nesting past one level, and an explicit rule that any request for a conditional is a request to go back to the API. ## Where the answer flips The signals above are about a notation that serves the people who could already use the API. It flips when the notation makes an illegal configuration impossible to write rather than merely inconvenient — that is a constraint the plain API did not have — or when the vocabulary is genuinely the domain's own and the people writing it think in those words, so that the notation is a translation rather than a dialect. It also flips when the same text is written far more often than it is read by engineers, because then the cost of teaching is amortised over a large audience doing one task repeatedly. The discipline is to say which of those applies, with a number attached, rather than to argue the aesthetics.
- The team's honest complaint is that the API is verbose. What do you propose instead of a notation?Named presets for the handful of configurations actually used, plus removal of knobs nobody sets. Both keep the member list, the signatures and the existing error path, and both are deletable in an afternoon if they turn out wrong. If the complaint is mistakes rather than length, give the values distinct types so the wrong one stops compiling.
- A notation has already shipped and is not repaying its cost. How do you make retiring it cheap?Keep all semantics in the API underneath so the notation is a pure translation with nothing of its own to lose. Then retirement is mechanical: expand each block into the calls it made, run the existing tests, and remove the layer. The cost of retirement is set the day the notation is designed, not the day you decide to drop it.
- What single number would most change your vote in the review?How many people outside the team that owns the API will author configurations, and how often. A large recurring authoring audience that does not otherwise read this code is the case that repays a vocabulary; a handful of edits a quarter by the owning team is the case that does not.
saying these in an interview costs you the question
- Any repeated call sequence justifies a notation
- A notation is cheap because it is only a thin layer over an existing API
- Fewer characters at the call site means a simpler system
- The notation needs no tests of its own since the API underneath is tested
- Reading well in a demo predicts reading well under maintenance
- Adding a conditional to the notation is a small extension