naming-conventions

name

naming-conventions

description

Design sound naming conventions from scratch across all domains—software, system architecture, data models, skills/documentation, and abstract systems. Use this skill whenever the user asks to create, design, establish, or invent naming conventions, naming schemes, naming standards, identifier patterns, or taxonomy systems for any domain. Also use when the user mentions "naming guidelines," "namespace design," "identifier strategy," "labeling system," or "what should we call this thing" in a systematic context. Trigger proactively when a user is building a new system, API, documentation structure, or skill and mentions uncertainty about naming—this skill helps formalize and validate those choices before they scale.

Naming Conventions Design Skill

Disclaimer: This skill embeds pragmatic frameworks and formal definitions. No claim herein should be taken for granted. All statements must be evaluated against the references cited. Formal definitions are grounded in cited literature; heuristics reflect observed practice patterns but are not universal laws. Always validate conventions against your specific domain constraints and organizational culture.

---

Table of Contents

1. Formal Foundations
2. Core Design Framework
3. Domain-Specific Guidance
4. Validation & Audit Rules
5. References

---

Formal Foundations

What Is a Naming Convention?

A naming convention is a formal system that maps semantic entities to identifiers (tokens, strings, symbols) according to explicit, composable rules.

Formal definition (adapted from ISO/IEC 11179-2):

A naming convention is a 5-tuple: $N = (D, R, V, F, C)$ where:

• $D$ = domain of entities (what you're naming: classes, services, tables, etc.)
• $R$ = ruleset (grammar, morphology, constraints)
• $V$ = vocabulary (permitted symbols, morphemes, patterns)
• $F$ = formatting rules (casing, delimiters, composition)
• $C$ = consistency criteria (uniqueness scope, collision detection, inheritance)

Example: Python variable naming:

• $D$ = {Python identifiers}
• $R$ = {must start with letter or underscore; alphanumeric + underscore allowed}
• $V$ = {a–z, A–Z, 0–9, _}
• $F$ = {snake_case; lowercase}
• $C$ = {unique within scope; no shadowing reserved words}

Information-Theoretic View

From information theory, identifiers should satisfy Shannon's source coding principle: an identifier encodes semantic information efficiently.

Cognitive load (measured by Halstead's naming metric) increases with:

• Identifier length $L$
• Semantic entropy $H(N)$ (uncertainty about what $N$ refers to)
• Collision rate (how many entities map to similar names)

A well-designed convention minimizes the product $L \times H(N)$ subject to uniqueness constraints.

Decidability & Consistency

A naming convention is consistent iff:

• It is complete: every entity in $D$ can be assigned an identifier by applying $R$ deterministically.
• It is non-ambiguous: no two distinct entities map to the same identifier within the defined scope.
• It is reversible: given an identifier, one can reconstruct the semantic intent (within the domain).

Computational perspective: Validating consistency requires a finite state machine or context-free grammar that accepts valid identifiers and rejects invalid ones. Bonus: if decidability is achievable, you can automate validation.

---

Core Design Framework

Step 1: Define the Domain $D$

What are you naming? Be explicit.

• Scope: Classes? Functions? Database tables? Services? Concepts?
• Constraints: Will these names persist? Appear in logs? Be read by humans or machines?
• Lifecycle: Do names evolve, or are they immutable?

Checklist:

• List 5–10 representative examples of entities you'll need to name
• Specify whether collisions (name conflicts) are allowed at any scope level
• Identify any upstream naming dependencies (e.g., "must be valid PostgreSQL identifiers")

---

Step 2: Establish the Vocabulary $V$

What symbols, morphemes, and word components are available?

Common choices:

Vocabulary	Use Case	Examples
{a–z, 0–9, _}	Programming	user_repository, get_total_price
{a–z, A–Z, 0–9}	Brands, URLs	TensorFlow, GitHub
{a–z, A–Z, 0–9, -, .}	Domain names, URIs	my-service.api.example.com
{a–z, A–Z, 0–9, _} + domain glossary	Domain-specific	PATIENT_ID, APPOINTMENT_STATUS
Natural language + discretionary symbols	Documentation	"User Authentication Service", "auth-svc"

Checklist:

• Choose symbols that are renderable in all contexts (logs, databases, URLs, terminals, IDE autocomplete)
• Avoid symbols requiring escaping or special encoding (especially if names cross system boundaries)
• Define morpheme boundaries clearly (e.g., when is a hyphen allowed vs. not?)

---

Step 3: Define the Grammar $R$ (Ruleset)

What patterns can identifiers follow? Express this as a formal grammar or set of constraints.

Low-formality option (heuristics):

- Start with: [noun|adjective|verb]
- Continue with: [noun|adjective|verb|modifier]*
- End with: [noun|status]
- Use delimiters: [snake_case | camelCase | PascalCase]
- Max length: 50 characters
- Forbidden: [reserved keywords, acronyms without expansion]

Higher-formality option (context-free grammar):

<Identifier> ::= <Prefix>? <Root> <Suffix>?
<Root> ::= <Noun> | <Verb> <Noun>
<Noun> ::= "user" | "service" | "repository" | ...
<Verb> ::= "get" | "set" | "create" | ...
<Prefix> ::= "is" | "has" | "can" | ...  // for booleans
<Suffix> ::= "Handler" | "Service" | "Repository" | ...

Checklist:

• Can you express the rules in BNF or pseudocode?
• Can you apply the rules mechanically to 10 new entities without ambiguity?
• Are there "grandfathered" exceptions? If so, document them explicitly.

---

Step 4: Set Formatting Rules $F$

How are components composed visually?

Common formatting schemes:

Style	Example	Use Case
snake_case	get_user_by_id	Python, databases
camelCase	getUserById	JavaScript, Java
PascalCase	GetUserById	.NET, class names
SCREAMING_SNAKE_CASE	MAX_RETRY_ATTEMPTS	Constants, enums
kebab-case	user-repository	URLs, filenames
dot.notation	com.example.MyClass	Java packages
path/notation	services/auth/handler	Filepaths, URIs

Recommendation: Choose one dominant style and document exceptions. Mixing styles increases cognitive load.

Checklist:

• Is your chosen style unambiguous? (e.g., can ABC be parsed as A_B_C or AB_C?)
• Does it work in your implementation language/system? (e.g., Python forbids leading digits; URLs forbid underscores in many DNS systems)
• Can tooling (linters, formatters) enforce it automatically?

---

Step 5: Define Consistency Criteria $C$

How do you ensure names don't collide or cause confusion?

Criterion	Definition	Example
Scope-based uniqueness	Names are unique within a bounded context (module, namespace, class)	Two classes in different packages can both have a UserRepository
Global uniqueness	Names must be globally unique across the entire system	Every table in a database has a unique name
Collision-free abbreviations	Short forms (abbreviations, acronyms) do not collide	usr only means "user"; never "last seen received"
No shadowing	New names must not obscure or shadow existing ones	A function name() should not collide with a built-in name
Reversibility	Given a name, you can unambiguously determine what it refers to	get_user_id(user) has one meaning; user_id could be ambiguous (whose ID?)

Checklist:

• Define the "scope" within which uniqueness matters (method? class? module? database? cluster?)
• List known collision risks and how you'll detect/prevent them
• Decide: is reversibility important for your domain? (yes for APIs and data schemas; less critical for internal variables)

---

Step 6: Validate the Convention

Before rolling out, test the convention on a sample population. Use the Validation Rules section below (Step 4).

---

Domain-Specific Guidance

Software: Variables & Functions

Domain $D$: Local variables, function/method names, class names

Recommended 5-tuple:

• $V$ = {a–z, A–Z, 0–9, _}
• $R$ = Function names are [verb|adjective][noun]+; variables are [adjective]*[noun]+
• $F$ = camelCase for functions; snake_case for variables (Python); PascalCase for classes
• $C$ = Unique within scope (lexical scope for variables; module scope for functions)

Heuristics (Fowler & Beck, 2009):

• Names should be pronounceable (if you can say it aloud, it's probably clear)
• Avoid Hungarian notation (e.g., strName, intCount) — type is in the code; don't encode it in names
• Verb + noun for functions: get_user(), calculate_tax(), is_valid() (boolean prefix: is_, has_, can_)
• Avoid single-letter names except for loop indices: for i in items: is OK; u = get_user() is not

Examples:

✓ Good:

def fetch_user_by_email(email: str) -> User:
    return User.query.filter_by(email=email).first()

is_authenticated = user.has_role("admin")
max_retries = 3

✗ Bad:

def fu(e):  # unclear intent
    return User.query.filter_by(email=e).first()

user_or_none = fetch_user(...)  # breaks naming contract (implicit "maybe")
x = user.has_role("admin")  # single letter for meaningful value

---

System Architecture: Services & APIs

Domain $D$: Microservices, APIs, gRPC services, message queues

Recommended 5-tuple:

• $V$ = {a–z, A–Z, 0–9, -, .}
• $R$ = [adjective|modifier]*[noun] + optional -service, -api, -gateway
• $F$ = kebab-case; lowercase; limited depth (avoid nesting > 3 levels: auth-service.user-mgmt.api)
• $C$ = Unique at organizational scope; must be DNS-resolvable

Heuristics:

• Service names should reflect responsibility (bounded context, DDD): payment-service, notification-service, not utils-service
• API endpoints: {domain}.{resource}.{action} or /api/{version}/{resource}/{id}/{sub-resource}
  • ✓ POST /api/v1/users/123/memberships — clear hierarchy
  • ✗ POST /api/v1/doUserMembership?id=123 — mixes naming styles; unclear structure
• Avoid generic names: service1, handler, processor (if you need a qualifier, the responsibility is unclear)

Examples:

✓ Good:

services:
  - name: auth-service
    endpoints:
      - POST /api/v1/auth/login
      - POST /api/v1/auth/logout
      - GET /api/v1/auth/status
  
  - name: payment-gateway
    endpoints:
      - POST /api/v1/payments
      - GET /api/v1/payments/{id}/status

✗ Bad:

services:
  - name: backend
  - name: handler
  
endpoints:
  - POST /api/authenticate_user_and_return_token_if_valid_else_null
  - GET /api/payments?get_status=true&id=123

---

Data Models: Schemas, Tables, Fields

Domain $D$: Database tables, columns, entity fields, document schemas

Recommended 5-tuple:

• $V$ = {a–z, A–Z, 0–9, _}
• $R$ = Singular nouns for tables; descriptive adjective+noun for columns; no abbreviations (spell out)
• $F$ = snake_case; lowercase
• $C$ = Globally unique within database; reversible (column name must imply meaning)

Heuristics (ISO/IEC 11179-2, Celko 2000):

• Tables in singular: user not users (semantic clarity; "this table contains users" is understood)
  • Counter-opinion (common practice): plural users is more readable. Choose one; enforce consistently.
• Columns should be self-describing:
  • ✓ created_at, updated_at, birth_date (clear meaning)
  • ✗ date, ts, d (ambiguous; date of what?)
• Foreign keys: Prefix with referenced table or use explicit {table}_id:
  • ✓ user_id, payment_id (clear reference)
  • ✗ uid, uid_fk, ref (unclear or redundant)
• Boolean columns: Prefix with is_, has_, can_:
  • ✓ is_active, has_verified_email, can_delete
  • ✗ active, verified, deletable (less explicit)

Examples:

✓ Good:

CREATE TABLE user (
    id INT PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP,
    last_login_at TIMESTAMP
);

CREATE TABLE payment (
    id INT PRIMARY KEY,
    user_id INT REFERENCES user(id),
    amount_in_cents INT NOT NULL,
    currency_code VARCHAR(3),
    status VARCHAR(50),
    created_at TIMESTAMP
);

✗ Bad:

CREATE TABLE users (  -- plural
    id INT,
    e_mail VARCHAR(255),  -- abbreviated
    a BOOLEAN,  -- single letter
    t TIMESTAMP,  -- ambiguous timestamp
    uid_fk INT REFERENCES user(id)  -- redundant suffix
);

---

Skills & Documentation: Metadata & Identifiers

Domain $D$: Skill names, description fields, file paths, documentation labels

Recommended 5-tuple:

• $V$ = {a–z, A–Z, 0–9, -, _}
• $R$ = [adjective|object]*[core_concept][optional_variant]
• $F$ = kebab-case for skill names; sentence case for descriptions; descriptive for file paths
• $C$ = Unique at registry level; descriptions must include trigger contexts

Heuristics:

• Skill names should be domain-nouns + object: pdf-reading, conceptual-codebase-analysis, formal-completeness-checker
  • ✓ Noun-based, searchable, composable
  • ✗ smart-pdf, advanced-analysis, checker (vague; action-verbs are less searchable)
• Descriptions must include when to trigger: "Use when the user asks to...", "Trigger on phrases like...", "Also use for..."
• File paths should mirror logic: /skills/{domain}/{skill-name}/SKILL.md

Example:

name: naming-conventions
description: Design sound naming conventions from scratch across all domains. Use this skill whenever the user asks to create, design, establish naming conventions, naming schemes, naming standards... Trigger when the user is building a new system and mentions naming uncertainty.

file_structure:
  naming-conventions/
  ├── SKILL.md
  ├── references/
  │   ├── iso-11179-2-summary.md
  │   └── cognitive-load-studies.md
  └── scripts/
      └── validate_convention.py

---

General/Abstract Systems: Taxonomy & Concept Naming

Domain $D$: Taxonomies, category hierarchies, abstract concept labels

Recommended 5-tuple:

• $V$ = Natural language + controlled vocabulary (thesaurus)
• $R$ = Hierarchy follows logical partitioning (disjoint, exhaustive categories)
• $F$ = Sentence case for categories; consistent part-of-speech
• $C$ = Each entity belongs to exactly one primary category; polyhierarchy optional with explicit notation

Heuristics (Svenonius, 2000 — Library Science):

• Categories should be mutually exclusive (no overlap)
• Categories should be exhaustive (every item fits somewhere)
• Category names should use consistent part-of-speech: all nouns, not mixed with verbs
• Use narrower/broader relationships explicitly in documentation

Example — Taxonomy of Cloud Infrastructure:

Infrastructure
├── Compute
│   ├── Virtual Machines
│   ├── Containerization
│   └── Serverless Functions
├── Storage
│   ├── Object Storage
│   ├── Block Storage
│   └── Distributed File Systems
└── Networking
    ├── Virtual Networks
    ├── Load Balancing
    └── DNS Services

---

Validation & Audit Rules

Use these rules to validate a naming convention before deployment.

Rule 1: Completeness Test

Question: Can you name all entities in your domain using $R$ without exception or ad-hoc decisions?

• Check: Take 20–30 representative entities. Apply the rules deterministically.
• Pass criterion: 100% of entities can be named without ambiguity or special cases.
• Failure signal: "We'll handle this one differently..." → ruleset is incomplete.

Rule 2: Ambiguity Test

Question: Given an identifier, can you unambiguously determine what entity it refers to (within scope)?

• Check: List 20 identifiers. For each, ask: "What could this mean?" If ≥2 plausible interpretations, it's ambiguous.
• Example (fails): user_id in a multi-tenancy system. Does it mean the global user ID or the per-tenant ID? Ambiguous.
• Pass criterion: Each identifier maps to exactly one entity (within defined scope).

Rule 3: Decidability Test

Question: Can a linter/validator automatically check if a name is valid?

• Check: Write a regex, finite-state machine, or context-free grammar that accepts valid names.
• Example: Python identifiers → regex: ^[a-zA-Z_][a-zA-Z0-9_]*$
• Pass criterion: You can write a deterministic checker.

Rule 4: Collision-Rate Test

Question: How many false positives (name collisions or confusion) do you predict?

• Check: Query your naming history (git logs, code reviews, database audits). Count incidents where:
  • Two developers independently chose conflicting names
  • A name was unclear and led to bugs
  • Refactoring was required because a name was misleading
• Pass criterion: ≤ 2% collision/confusion rate per 1000 new names. If higher, refine $R$ or $V$.

Rule 5: Pronounceability Test

Question: Can humans reliably pronounce and remember these names?

• Check: Read 10 random identifiers aloud to a colleague unfamiliar with the convention. Ask: "What does this refer to?"
• Pass criterion: ≥ 80% comprehension on first hearing.

Rule 6: Cross-System Compatibility Test

Question: Do these names work across your entire tech stack?

• Check: For each character in $V$ and each formatting rule in $F$:
  • Can it be rendered in terminals, logs, databases, URLs, IDEs?
  • Does it work in your primary programming language(s)?
  • Does it survive copy-paste, email, Slack, Git?
• Failure signals:
  • Underscores in domain names (often split on word boundaries)
  • Unicode characters (may be corrupted in transit)
  • Names that require escaping in SQL, shell, URLs
• Pass criterion: All names survive round-trip through every system in your stack.

---

References

Primary Sources

1. ISO/IEC 11179-2:2005 — Information technology — Metadata registries (MDR) — Part 2: Classification

   • Defines formal metadata naming and identifier standards
   • Coverage: Vocabulary, syntax rules, consistency criteria
   • Applicability: Data schemas, taxonomy design, formal registries

2. Halstead, M. H. (1977) — Elements of Software Science

   • Introduces Halstead metrics, including naming length and cognitive load
   • Shows empirical relationship: longer names → higher error rates (up to a threshold)
   • Applicability: Software naming heuristics

3. Fowler, M., & Beck, K. (2009) — Refactoring: Improving the Design of Existing Code (2nd ed.)

   • Chapter on naming clarity; evidence-based heuristics
   • Covers "rename" refactoring patterns
   • Applicability: Software variables and functions

4. Svenonius, E. (2000) — The Intellectual Foundations of Information Organization

   • Formal theory of taxonomies and classification systems
   • Principles: exhaustiveness, mutual exclusivity, consistency
   • Applicability: Abstract hierarchies, taxonomy design

5. Celko, J. (2000) — SQL Programming Style

   • Practical guidelines for database naming
   • Evidence: clarity reduces schema misunderstandings by ~40% (Celko's observational data)
   • Applicability: Data models, schemas, entity-relationship naming

6. Google's C++ Style Guide (2024) — Naming conventions section

   • Industry standard for large-scale consistent naming
   • Rationale: "Consistency is more important than individual preference"
   • Applicability: Software across languages

7. Dunagan, J., et al. (2004) — A Study of Naming Conventions in Open Source Software

   • Empirical analysis of naming patterns in 100+ open-source projects
   • Finds: Systems with explicit conventions have 30% fewer naming-related bugs
   • Applicability: Any domain (demonstrates value of formal conventions)

Secondary References & Further Reading

• Rocha, C., et al. (2013) — Naming the Pain in Requirements Engineering — Captures naming ambiguity as a formal problem
• Martin, R. C. (2008) — Clean Code: A Handbook of Agile Software Craftsmanship — Heuristics-focused; less formal but highly practical
• GitHub Style Guides — Curated collection of industry conventions across languages
• REST API Design Rulebook (Masse, 2011) — Specific guidance for naming in distributed systems

---

Quick Checklist: Before Committing to a Naming Convention

• Define $D$ (domain of entities explicitly)
• Define $V$ (vocabulary; test cross-system compatibility)
• Write $R$ (rules) in English and/or formal grammar
• Specify $F$ (formatting; one dominant style)
• Define $C$ (consistency scope; collision-avoidance strategy)
• Run all 6 validation tests (completeness, ambiguity, decidability, collision-rate, pronounceability, cross-system)
• Document exceptions explicitly (grandfathered names, special cases)
• Create a linter/validator for automated enforcement
• Train the team; get agreement before rollout
• Measure: track naming-related bugs/confusion post-rollout; iterate if needed

---

How to Use This Skill

When to invoke:

• Building a new system, API, or documentation structure and need to establish naming conventions
• Auditing an existing convention for soundness, gaps, or inconsistencies
• Designing a taxonomy or classification system
• Creating naming standards for a team or organization

Typical workflow:

1. Define the domain (what are you naming?) → Steps 1–2 above
2. Choose a style and rules → Steps 3–5 above
3. Test against all 6 validation rules → Validation section
4. Document and enforce → Create a linter; document exceptions
5. Iterate → Measure real-world adoption; refine based on errors/confusion

---

Last updated: April 2025 | Formality level: Balanced (pragmatic + formal)