apply-domain-based-naming

Apply Domain-Based Naming

Name code elements using the vocabulary of the problem domain so that code reads like the business it models.

Why This Is Best Practice

Adopted by: Evans' Domain-Driven Design (adopted at Amazon, Netflix, Spotify, and virtually every large-scale service-oriented architecture); Google's internal style guides; Microsoft's .NET naming guidelines (domain vocabulary preferred over technical vocabulary). Impact: When code uses domain language, domain experts can participate in code review, specification errors are caught before they become bugs, and new engineers who know the domain can read the code without a translator. The cognitive translation tax — "ah, record means order" — compounds across every file read, every PR review, every incident diagnosis. Evans (2003) cites vocabulary mismatch as the primary cause of requirement misunderstanding between domain experts and engineering teams. Why best: Technical naming (suffixes like Manager, Handler, Data, DTO; directories named utils/, helpers/, common/) describes implementation artifacts, not domain concepts. When the code changes its implementation (e.g., switches from a relational to a document store), technically-named code becomes misleading. Domain-named code remains accurate as long as the business concept holds — which is far longer than any implementation detail.

Sources: Evans, "Domain-Driven Design" (Addison-Wesley, 2003); Dan North, "CUPID—for joyful coding" (2022); Google, "Google Style Guides"; Feathers, "Working Effectively with Legacy Code" (Prentice Hall, 2004)

Status: Emerging — domain naming is a well-understood practice within DDD circles; its framing as a standalone CUPID property by Dan North (2022) is gaining adoption but not yet majority-recognized independently of DDD.

Steps

1. Identify domain vocabulary first

Before naming anything, establish the terms the domain uses. If a glossary does not exist, create one.

• Interview domain experts: what do they call the entities, actions, and states in their work?
• Capture the terms in a glossary (docs/glossary.md or similar) alongside the code
• Resolve conflicts: if engineering says "transaction" and finance says "payment", pick one and use it everywhere

---

2. Name entities as domain nouns

Classes, structs, tables, and types represent domain concepts. Name them with domain nouns, not technical patterns.

Technical (avoid)	Domain-based (prefer)
UserRecord	Customer
OrderDTO	Order
PaymentManager	PaymentProcessor
AbstractFactory	(name the thing it makes)
DataHelper	(name what data it operates on)

# Bad — technical suffix adds no meaning
class UserDataRecord:
    user_id: str
    email_address: str

# Good — the domain calls this a Customer
class Customer:
    id: str
    email: str

---

3. Name operations as domain verbs

Functions and methods name actions. Use the verb the domain uses, not a generic technical verb.

Technical (avoid)	Domain-based (prefer)
processPayment()	chargeCard(), authorizePayment()
handleOrder()	placeOrder(), cancelOrder(), fulfillOrder()
updateUser()	changeEmail(), promoteToAdmin(), deactivateAccount()
getData()	fetchInvoice(), lookupCustomer()

// Bad — "process" hides what actually happens
async processPayment(payment: Payment): Promise<void>

// Good — domain knows the difference between authorize and capture
async authorizePayment(payment: Payment): Promise<Authorization>
async capturePayment(auth: Authorization): Promise<Receipt>

---

4. Structure directories by domain, not by technical layer

File organization is naming at the module level. Technical layers (models/, services/, controllers/, utils/) create a structure that mirrors the framework, not the domain. Domain-based structure mirrors the business.

# Bad — technical layers
src/
  models/user.py, order.py, product.py
  services/user_service.py, order_service.py
  controllers/user_controller.py, order_controller.py
  utils/

# Good — domain structure
src/
  customers/customer.py, customer_store.py
  orders/order.py, order_processor.py, order_store.py
  catalog/product.py, catalog.py

Domain-structured code puts everything related to a concept in one place. When an Order changes, you look in orders/.

---

5. Maintain consistency across the entire stack

The same concept must have the same name in every layer: API, database, logs, error messages, documentation. Inconsistency forces every reader to maintain a mental translation table.

• API returns customer_id → database column is customer_id → log message says customer_id → not user_id in one place and account_id in another
• Run a grep across the codebase: how many terms refer to the same concept? Normalize to one.

Common Mistakes

Domain prefix on every class. InvoiceInvoiceProcessor, OrderOrderRepository — don't repeat the domain prefix when the file path already provides context. Inside orders/, the class is just Processor or Repository.

Naming for the current implementation. SQLUserRepository encodes the storage technology in the name. When you switch to MongoDB, the name is wrong. Name what the unit does, not how: UserRepository or UserStore.

Over-precise names that don't exist in the domain. PendingUnshippedDomesticOrderWithDiscountApplied is technically accurate but no domain expert uses that phrase. If the domain has a name for the concept, use it; if not, use the simplest name that is accurate.

utils/ and helpers/. These are wastebaskets, not domain concepts. When code ends up in utils/, it means the domain concept it belongs to has not been named yet. Name it and move the code there.

When NOT to Use

• Library/framework internals — library code often uses technical vocabulary by necessity (e.g., middleware, handler, resolver); these are infrastructure concepts, not domain concepts
• Generic utilities with no domain meaning — a retry function or a parse_iso_date helper has no domain concept to be named after; technical names are correct here
• Early prototyping — when the domain is not yet understood, technical placeholders are fine; apply domain naming once the concepts stabilize