Examples beat adjectives

Why an example carries more than a paragraph

“Write a validation error message that is helpful and friendly” produces something. Which something depends entirely on what the words helpful and friendly pull towards, and you have no control over that.

Three examples specify the same thing exactly:

Email: "That email address is missing an @ symbol."
Date:  "That date is in the future. Bookings can only be for today or earlier."
Money: "Amounts can have at most 2 decimal places. You entered 3."

Now the register, the length, the sentence structure, the decision to state what was wrong rather than what is required, and the absence of “please” and exclamation marks are all fixed: by demonstration rather than description. A fourth message will match, and you did not have to know that you cared about any of those properties.

This is the same reason a worked example beats a rule in a specification. Examples encode the properties you would not have thought to name, and those are usually the ones that make the difference between right and nearly right.

The translation table for common adjectives

Every vague word in a request has a concrete form. The exercise of finding it is ten seconds and it is most of the value of a specification.

• Clean → follows the existing pattern in X; here is the file.
• Efficient → a single database round trip, not one per row.
• Simple → under 40 lines, no new dependencies, no new abstraction.
• Consistent → matches the naming in models/order.py, which is the reference.
• Well tested → these five cases must be covered, named here.
• Idiomatic → here are two functions from this repository; match them.
• Production ready → has a timeout, a retry policy, a metric, and a documented failure mode.

The last one is worth dwelling on. “Production ready” is the single vaguest phrase in software and it can be turned into a four-item checklist that anyone can verify.

Use the words your domain actually uses

A specification full of item, object, record, process and handle is a specification that has not yet decided anything.

Use the vocabulary of the business, exactly, and use each word to mean one thing. If finance says invoice, credit note and statement, then those three words appear in the specification, in the code, in the table names and in the conversation. If a shipment can contain items from several orders, that sentence goes in, because it is the fact that determines the data model.

This idea has a name in domain-driven design (the ubiquitous language) and its practical payoff is that the gap between what the business said and what the code does becomes visible. A function called processItems cannot be checked against a requirement. A function called allocate_stock_to_shipment can.

There is a second payoff now. Precise domain vocabulary is a much stronger signal to a generator than generic vocabulary, because it narrows what is being asked for. “Reconcile the settlement file against the ledger” produces something far closer to what you want than “process the data”, not because of any magic, but because the first sentence carries information and the second does not.

Show the shape of the output

When you want a particular structure, show it rather than describe it.

{
  "invoice_id": "INV-2026-000412",
  "lines": [
    {"sku": "TS-BLUE-M", "qty": 2, "amount_minor": 249900, "currency": "INR"}
  ],
  "total_minor": 249900,
  "base_currency": "INR",
  "issued_at": "2026-08-14T09:31:00Z"
}

One sample fixes the naming convention, the money representation, the date format, the nesting, the currency handling and the identifier format. Writing all of that as prose would take a paragraph and still leave ambiguity about whether total_minor includes tax.

The limit, stated honestly

Examples over-specify as easily as adjectives under-specify. Three error messages that all happen to start with “That” will produce a fourth starting with “That”, including where it reads badly. A sample JSON with two line items may produce code that assumes there are always at least two.

So choose examples that vary along the dimensions that do not matter and hold constant the ones that do. If length is irrelevant, make one example short and one long. If the number of items is irrelevant, show one with a single item and one with several. And where an example is deliberately not representative, say so in one line.

The underlying discipline is the same one as everywhere else in this module: decide what actually matters, and say it in the form that leaves the least room to be read differently.