write-discoverable-code

Write discoverable code

Coding agents discover code by searching for strings and reading small windows around the hits. They have no hover text, no jump-to-definition, and no memory between sessions. These rules make code resolvable in one search instead of five.

1. Names are search queries

• Exported symbols get 2–4 word names, at least one of them a domain word. diffUserObjects, not diff. queueEventForDispatch, not queue. Measured on a ~700k-line monorepo: 1-word exported names are globally unique 61% of the time; 3-word names 96%; 4+ words 98%. Three words is the knee of the curve. Use the shortest name that greps uniquely; put the rest in the doc comment.
• Give generic verbs their object. sanitizeEmailHtml, not sanitize; validateSmtpConfig, not validateConfig. Qualify only as far as uniqueness requires, then stop.
• One definition site per symbol. Never copy a function between files; move it and delete the original in the same change. Shared helpers get one concept-named home and are imported everywhere else.
• Do not rely on the module path to disambiguate a generic name. The import that disambiguates users/diff.ts from orders/diff.ts sits at the top of the file; the search hit is at line 300. Put the context in the symbol (formatDurationMs), not the folder. Exception: rigid, absolute conventions where the path carries the meaning (e.g. every contract file exporting Input/Output).
• One concept, one spelling. Pick organizationId or orgId and use it everywhere; every synonym splits every future search in half. Reuse existing vocabulary in the codebase you are editing rather than introducing near-synonyms.
• When behavior or audience changes, rename in the same commit. A stale name is misinformation with a 100% open rate — that includes visibility markers: a _private helper that other modules now import needs a public name.
• Filenames are names too — never use bare-role filenames. config.ts, types.ts, utils.ts, helpers.ts, handlers.ts say nothing in a search result and collide with every other module's config/types/utils in the repo. Prefix the domain: billing-plan-config.ts, not config.ts. (index.ts is acceptable only as a thin re-export entry point.)