find-clear-names

Audience first

The naming rule depends on who reads the name. Determine the audience before choosing a name.

Developer-facing — variables, functions, classes, DB tables/columns, endpoint paths, query params, internal request/response fields, event names, error codes, config keys, env vars, CLI flags, file/module names:

• Clear and intuitive within the domain
• Industry-standard terms stay: idempotency_key in payments, nonce in auth, TTL in caching
• No abbreviations, no vague generics, no implementation leakage

End-user-facing — error messages, public API response fields, external SDK methods, third-party webhook events, CLI output text:

• Plain language, zero jargon
• No domain expertise assumed
• If a term is technical on the dev side, translate it for users

Step 1 — Detect languages and scan existing names

git ls-files | grep -oE '\.[^.]+$' | sort | uniq -c | sort -rn