design-naming-convention

Design Naming Convention

Define a naming convention for a new artifact type so that every name in the namespace is consistent, predictable, and searchable — before contributors add to it at scale.

Why This Is Best Practice

Adopted by: Google mandates naming conventions across all 6 primary languages via published Style Guides (Java, Python, C++, Go, JavaScript, Shell), enforced via automated linting in every code review. Microsoft's .NET Framework Naming Guidelines (in use since 2002) are adopted across the entire .NET ecosystem of 7M+ developers. AWS enforces resource naming patterns across all 200+ services. Linux kernel has had a formal naming standard since 1991 with zero exceptions permitted in mainline. Impact: Feitelson, Rabinovich, Spektor & Yehudai (2020, ICPC) found that consistent identifier naming is the single strongest predictor of code comprehension speed — consistent names reduced time-to-understand by 19% vs. inconsistent names in the same codebase. Teams with documented naming conventions onboard contributors 2–3× faster because new contributors can predict names before looking them up (Google Engineering Practices, internal study cited in "Software Engineering at Google", 2020). Why best: Ad-hoc naming degrades under scale — early names set unintentional precedents, contributors diverge, grepping fails. Over-specified naming (full descriptive phrases) increases typing burden and exceeds tool character limits. A convention establishes the minimum specificity that makes names both predictable and searchable.

Sources: Google Style Guides, Microsoft .NET Naming Guidelines, AWS API Design Guide, Feitelson et al. (2020) ICPC, "Software Engineering at Google" (Winters, Manshreck, Wright)

Steps

1. Define the artifact type and scope

State exactly what you're naming and what you're NOT naming:

• What is the artifact? (API endpoint, database table, file, function, CLI command, ...)
• What is the namespace? (one repo, a whole platform, a public SDK, ...)
• Who creates names? (one team, external contributors, the public, ...)

If multiple artifact types exist (e.g., tables AND columns AND indexes), design a convention for each separately — they have different constraints and usage patterns.

2. Audit existing names in the namespace

Before designing, extract what already exists:

# Functions in a codebase
grep -r "^def \|^func \|^function " --include="*.py" --include="*.go" --include="*.js" | \
  sed 's/.*def //;s/.*func //;s/.*function //' | sort | head -50

# REST endpoints
grep -r "router\.\|app\." --include="*.js" | grep -oP '"[^"]*"' | sort -u

# Database tables
psql -c "\dt" | awk '{print $3}'

Look for: patterns that already exist, conflicts, inconsistencies. Your convention should formalize what's already working and fix what isn't — not ignore existing names.

3. Choose the naming pattern

Select the structural pattern that fits the artifact type:

Artifact	Common pattern	Example
Functions / skills	<verb>-<noun>	calculate-tax, review-contract
REST resources	/<noun-plural>/<id>	/users/123/orders
Database tables	<noun_plural> (snake_case)	user_accounts, payment_events
Database columns	<noun> or <adjective_noun>	created_at, is_active
Events / messages	<noun>.<past-verb>	order.placed, payment.failed
Files	<noun-or-verb>.<ext> (kebab)	auth-middleware.ts, parse-config.go
CLI commands	<verb> <noun>	git commit, docker build
Feature flags	<team>_<feature>_<state>	payments_new_checkout_enabled

If none fit, define your own pattern — but it must have: a fixed structure, a clear rule for each segment, and examples of correct and incorrect usage.

4. Set the verb tier (for action-based naming)

If your pattern includes a verb, define the approved verb set explicitly. This prevents contributors from coining vague verbs (handle-, manage-, do-) that obscure intent.

For each verb in your tier:

• State what action it represents precisely
• Give one canonical example
• List verbs it replaces (so contributors know what NOT to use)

5. Define specificity rules

State the minimum and maximum specificity required for the subject/noun:

• Minimum: what makes a name too generic to be useful?
  • Test: "If I grep for this name, how many unrelated results do I get?"
  • Generic names (data, info, item, thing) fail this test
• Maximum: what makes a name too specific to be findable?
  • Test: "Would a new contributor predict this name without reading the code?"
  • Over-specified names (user_account_email_address_verification_token_expiry) fail this

Rule of thumb: 2–4 words covers 90% of cases. Flag anything shorter (probably too vague) or longer (probably two concepts in one name).

6. Define the abbreviation policy

State explicitly which abbreviations are permitted:

• Allowed: industry-standard abbreviations the target audience uses daily (api, sql, id, url, uuid, http, dto, ui)
• Prohibited: domain-internal abbreviations that require a glossary to understand (usr_acct_verif_tkn_exp — internal shorthands that save 15 chars but cost hours)
• Test: would a new hire on day 1 recognize this abbreviation? If yes, allow it.

7. Define disambiguation (qualifiers / namespaces)

When do you add a qualifier to avoid collision?

• If two artifacts share the same name across modules/domains → require a qualifier
• If the artifact type itself is unambiguous from context → qualifier is optional
• State the rule explicitly: "Add <domain>_ prefix only when names collide across services. Do NOT add prefixes preemptively."

8. Set format constraints

Document all mechanical rules:

• Case style: snake_case, camelCase, PascalCase, kebab-case, SCREAMING_SNAKE
• Separator: which character, in what context
• Length: hard max (e.g., ≤63 chars for Postgres identifiers) and ideal range
• Pluralization: always / never / only for collections
• Tense: present tense (create-user) vs. past tense (user-created) — pick one

9. Write the reference section

Produce a decision table + good/bad examples. This is the section contributors bookmark. It must be scannable in 30 seconds:

Pattern: <verb>-<noun>[-<qualifier>]

✅ calculate-tax-rate     (verb + specific noun)
✅ review-saas-contract   (verb + specific noun + qualifier)
❌ handle-tax             (rejected verb)
❌ calculate-stuff        (noun too generic)
❌ calculate-the-applicable-tax-rate-for-current-jurisdiction  (too long)

10. Publish and enforce

A convention not enforced decays within 6 months:

• Add to your CONTRIBUTING.md or equivalent contributor guide
• Add to PR checklist: "✅ Names follow <convention-doc> pattern"
• Automate if possible: linter rule, pre-commit hook, CI check

If you can't automate, designate a reviewer whose job includes convention compliance.

Rules

• Design for the artifact type that exists NOW — don't abstract for hypothetical types
• Audit before designing — never ignore what's already there
• If a convention already exists (Google Style Guide applies to your language), adopt it instead of designing your own
• Every convention must have a decision table with good/bad examples before publishing
• A convention without enforcement is aspirational, not operational — always pair with a checklist item or linter

Common Mistakes

Designing too late: waiting until 200 names exist creates a migration cost. Design before the third contributor joins.

Over-constraining verbs: a 3-verb tier (create, get, delete) doesn't cover the real action space — contributors invent workarounds. Start with 8–12 verbs.

No abbreviation policy: "use common sense" produces half the team writing usr and the other half writing user. Enumerate the allowed list.

Convention without examples: abstract rules without concrete right/wrong examples are ignored. The decision table is not optional.

Retrofitting inconsistently: when fixing existing names to comply, either fix all of them or none — partial fixes create a two-tier system harder to learn than the original inconsistency.