When a host-language notation replaces a plain configuration API, what discoverability does a newcomer lose at the call site?
answer
- who has to be told versus who can see
- the menu against the sentence
- member list, not prose
- bare words drop the parameter label
- arity is what a block of statements loses
basics
~20 sA plain API advertises itself: its members, signatures and defaults are all reachable from the call site. A notation replaces that enumerable list with vocabulary a newcomer must be told about, and has to publish it some other way.
solid answer
~40 sWith a plain configuration API, the set of legal next moves is the receiver's member list, and each member's signature names its parameters and types. A newcomer learns the surface by exhausting that list. A notation made of bare words inside a block drops the labels: `retries 3` reads well to someone fluent and says nothing to someone who is not. How much survives depends on how the words resolve. Back each word with a real named member and completion, definition lookup and usage search keep working; resolve words by string lookup and nothing enumerates them, so a reference page becomes the only index. One thing is lost either way: a block of independent statements carries no arity, so which words are required is not visible at the call site.
code
pseudocode · 8 linesconfig = makeConfig()
config.setRetries(3)
config.setTimeoutSeconds(30)
pipeline {
retries 3
timeout 30
}go deeper
Remember the plain claim: an ordinary API shows you everything you may do next, and a custom notation shows you only what somebody already wrote. That is the trade in one sentence.
Explain the mechanics: which parts of discoverability come from members and signatures, which of them survive when notation words are real declarations, and why requiredness is lost either way.
Show that you price it. Name the mitigations you would insist on before approving a notation — a vocabulary page, shallow nesting, unavoidable required words — and how you would measure whether they worked.
Frame the standard: for whom is the extra vocabulary worth maintaining across teams and years, and what would make you retire a notation that stopped repaying its index cost.
## What discoverability means at a call site A surface is **discoverable** when the next legal move is visible from where you are standing, without leaving the file you are editing. Two things carry that property. The first is the **member list** of whatever value you are holding: the finite set of things you may do next. The second is the **signature** of each member — the names of its parameters, their types, their order, and which of them have defaults. A newcomer learns a discoverable surface by exhausting the list, not by being told about it. A domain notation trades exactly this property for reading order. Instead of `config.setRetries(3)`, the text says `retries 3` inside a block. The line reads better to somebody who already knows the vocabulary, and carries much less to somebody who does not. That is the trade a design review has to price, and it is a real cost rather than a matter of taste. ## What the plain API gives away for free - The **member list** is the menu: everything the surface accepts is enumerable from the receiver. - Each **signature** labels its parameters, so a bare `3` at a call site is named `retries` rather than guessed. - **Types** rule out whole classes of nonsense before the program runs, and a well-modelled unit makes a wrong unit a wrong type. - **Jump to definition** works on every member, because every member is an ordinary declaration with an ordinary definition. - **Find usages**, **rename** and deprecation notices are ordinary tooling operations, for the same reason. None of that is documentation anyone wrote. It is a by-product of the surface being made of declarations. ## What a notation keeps, and what it drops It matters enormously *how* the notation's words are resolved. Words that are real named members of a real named type keep most of the list. Words looked up by string key, or synthesized on demand, keep almost none of it. | Property at the call site | Plain API | Words backed by named members | Words resolved by name lookup | |---|---|---|---| | Enumerate the legal next words | yes | yes | no | | Parameter name visible beside the value | yes | partly — bare words | no | | Jump to a word's definition | yes | yes | no | | Find every place a word is used | yes | usually | text search only | | See which words are required | partly, via signatures | no | no | The last row survives every implementation choice. A parameter list states arity: omit a required argument and the call does not compile. A block of independent statements states nothing about arity — the words are siblings, not arguments — so "which of these may I leave out" is a fact the shape structurally cannot carry at the call site. Every notation pays that, however carefully it is built. ## Buying the discoverability back 1. **Back every word with a declaration.** If each word is a named member of the block's type, completion, definition lookup and usage search keep working, and the vocabulary is enumerable again. 2. **Publish a vocabulary reference** — one page: every word, what it takes, whether it is required, which block it is legal in. That page is a deliverable of the notation, not an optional extra, and it goes stale the moment the vocabulary grows. 3. **Keep the nesting shallow.** Every level is another vocabulary the reader must hold, and another place where a word is legal or illegal for reasons nothing on screen explains. 4. **Make required words unavoidable rather than documented.** If the result cannot be produced without them, the missing-word question answers itself. 5. **Measure it.** Sit with somebody who has never seen the notation, give them a configuration task, and count the times they leave the file. Then time the same task against the plain API. That number is the argument a review needs. ## What to say in the review A line that reads like a sentence tells a newcomer what it *means* without telling them what else is *available*, so "it reads better" does not answer the discoverability objection. The honest position is that a notation moves the index of the surface out of the call site and into a document, and somebody owns that document for as long as the notation lives. If the audience is small, technical and already fluent in the API underneath, that move buys little. If the audience writes configuration far more often than it writes code, and is genuinely helped by a shape that mirrors the domain, it can be worth paying for — but the price is a reference page, a worked example per block, and a periodic check that a newcomer can still find their way.
- Every word in our notation is backed by a real named member, so completion works. What is still less discoverable than the plain API?Requiredness and ordering. A member list shows what may be written, never what must be. A parameter list states arity; sibling statements do not, so nothing on screen says that one word is mandatory, that another may repeat, or that two of them conflict. Nesting adds a second gap: which words are legal in which block is a fact about the enclosing type, not about the word.
- How would you measure the discoverability cost instead of arguing about it in the review?Give the same configuration task to two people who know neither surface, one with the notation and one with the plain API, and count what leaves the file: documentation lookups, questions asked, and time to a first correct configuration. Repeat with a change to an existing configuration, which is the commoner task. Two runs are enough to tell a real gap from a preference.
- Does adding good documentation settle the objection?It reduces it rather than settling it. Documentation is a second artifact that drifts from the vocabulary, is read once, and is absent at the moment of failure. It is the right mitigation, but it converts a free property of the API into ongoing maintained work, which is precisely the cost the review is pricing.
A plain API is a printed menu: everything you may order is on it. A notation is ordering in the kitchen's own shorthand — faster once you know it, and silent about what else you could have asked for.
saying these in an interview costs you the question
- A notation is self-documenting because it reads like English
- Completion always works inside a notation block whatever the words resolve to
- Documentation fully replaces what the call site used to show
- Discoverability matters only for newcomers, not for maintainers
- If the words read well, nobody needs to know which are required