Two markers sit on the same declaration, one pure description and one causing behaviour, so how do you tell them apart?

## Metadata means whatever reads it Attaching a marker to a declaration adds a fact *about* the declaration. On its own the fact does nothing: it sits there, carried along with the code. Everything interesting — a report, a failed build, a boundary opened around a call — happens because something else read the fact and chose to act. This is the single idea the whole distinction rests on, and it is why the intuitive tests people reach for do not work: - **The name does not tell you.** A marker named for an intent reads exactly the same whether anything implements that intent or not. - **Members do not tell you.** A marker carrying a retry count looks purposeful, but a purely descriptive marker can carry members too, and a bare marker with no members can cause a great deal to happen. - **Placement does not tell you.** Markers of both kinds sit in the same position above the same declarations. ## The delete-and-observe test The reliable classification is behavioural, not syntactic. Remove the marker — in a scratch branch, not in the payroll service — and ask a precise question: **what observable thing is different now?** Then name the stage at which it differed. | What changed when you removed it | Classification | Example of the change | |---|---|---| | A report, an index, a generated document | **Description** | The ownership report lists one fewer method | | An editor hint or a warning, with the program unchanged | **Description** (tooling-facing) | A hint stops appearing for callers | | The build outcome | **Instruction, at build stage** | A rule stops being enforced and the build now passes | | What the program does when it runs | **Instruction, at run stage** | The payroll run is no longer re-attempted | Naming the stage matters because it is what a reviewer needs. "Instruction" alone does not distinguish a marker whose loss fails loudly at build time from one whose loss is invisible until a production failure that would have been absorbed. ## The line is not a property of the marker; it is a property of the system A marker that is description today becomes an instruction the day somebody writes something that acts on it. Nothing about the marker changes — no line above the payroll method is edited — and yet every declaration carrying it changes behaviour at once. Two consequences follow: 1. **Introducing a consumer for an existing marker is a behaviour change**, and it is one of the widest-blast-radius changes a codebase can take, because it applies to every declaration already marked. It deserves review as such, not as "wiring a new component". 2. **A marker nobody acts on is a liability in waiting.** It reads to a newcomer as if it does something. Either remove it or make the system report that nothing acts on it. The reverse direction is the same story: if the thing that acted on a marker is removed or stops matching, every marked declaration silently reverts to plain behaviour while the markers remain on screen, still reading like a promise. ## Why the distinction is worth making out loud Declarative configuration kept next to the code is genuinely valuable — the intent is visible at the declaration rather than buried far away — but only if the reader can tell which attached facts are promises about behaviour and which are notes. A codebase that mixes the two freely, with no convention distinguishing them, teaches its readers to ignore markers entirely, which is the worst outcome available: the instruction markers stop being read too. Practical conventions that hold the line: - Keep the two kinds **visually or lexically separable** — a naming convention, a separate namespace, a documented list — so a reader can classify without running an experiment. - **Publish which markers currently have a consumer.** This is the durable form of the delete-and-observe test, computed rather than remembered. - When a marker's classification changes, **treat it as a release-worthy event** and say so in the change description. - Resist adding a description-only marker that reads like an instruction; if it only documents something, a name that sounds like documentation costs nothing and prevents a wrong assumption. ## What an interviewer is listening for The weak answer classifies by vibe: "this one sounds like it does something". The strong answer says that attached metadata has no intrinsic meaning, gives the delete-and-observe test, names the stage at which the difference appeared, and adds the uncomfortable part — that the classification can change under you without any edit to the marked code at all.