Naming

Naming is the act of choosing identifiers for concepts, variables, functions, files, and modules so that code communicates its intent to every reader, human or machine.

“There are only two hard things in Computer Science: cache invalidation and naming things.” — Phil Karlton

Also known as: Naming Convention, Identifier Choice

Understand This First

• Ubiquitous Language – the ubiquitous language provides the domain terms that names should draw from.
• Domain Model – the domain model identifies the concepts that need names.

Context

You’ve built a domain model, perhaps established a ubiquitous language, and now someone (or some agent) needs to write actual code. Every function, variable, class, file, and module needs a name. This operates at the architectural level because naming decisions compound: a confusing name chosen on day one becomes the label that hundreds of later decisions are built on. Rename it six months later and you’re touching dozens of files across the codebase.

Naming has always mattered. What changed with agentic coding is the amplification effect. An AI agent treats the names it finds in a codebase as its primary signal for understanding what things do. A human developer can compensate for a bad name by reading surrounding context, asking a colleague, or checking documentation. An agent reads processData() and proceeds as if that name tells the full story. If the function actually calculates sales tax, the agent will misunderstand every call site it encounters.

Problem

How do you choose names that make code understandable to both humans and AI agents, and keep those names consistent as the codebase grows?

A poorly named codebase doesn’t break immediately. It degrades gradually. A function called handleStuff tells no one anything. A variable called temp in a financial calculation hides whether it holds a temperature or a temporary value. When three developers each pick a different convention for the same kind of thing (getUserById, fetch_customer, loadAccount), the codebase becomes a translation exercise rather than a reading exercise. An agent working in that codebase will generate code that follows whichever style it last encountered, introducing a fourth convention. Then a fifth.

Forces

• Good names require understanding the domain, not just the code. You can’t name a function well until you know what it does in business terms.
• Short names are easy to type but often ambiguous. Long names are precise but clutter the code and strain readability.
• Teams have mixed conventions inherited from different eras, frameworks, and personal preferences. Unifying them costs effort.
• AI agents imitate what they see. Inconsistent naming in existing code produces inconsistent naming in generated code, and the drift accelerates.

Solution

Treat naming as a design activity, not an afterthought. Every name should answer the question: if someone reads this identifier with no other context, what will they expect it to do or contain?

The most important rule is that names should describe what something represents, not how it’s implemented. monthlyRevenue is better than float1. sendInvoice() is better than process(). Once you’ve chosen descriptive names, keep them consistent. If you use get as the prefix for data retrieval, use it everywhere. Don’t mix get, fetch, load, and retrieve for the same operation unless they mean genuinely different things.

Follow the conventions of your language and ecosystem too. Python uses snake_case for functions and variables. JavaScript uses camelCase. Rust uses snake_case for functions and PascalCase for types. Fighting the ecosystem’s conventions creates friction for every reader, including agents that have been trained on idiomatic code in each language.

Write your naming conventions down. A short document listing patterns (“we prefix boolean variables with is_ or has_”, “we name event handlers on_<event>”, “we use the domain glossary terms, not synonyms”) gives both human developers and agents a reference point. Include this document in the agent’s context when generating code, just as you would include a specification or instruction file. The document doesn’t need to be long. A page of rules with examples works. What matters is that it exists and that agents can read it.

How It Plays Out

A team builds a logistics API. Early on, different developers name related endpoints inconsistently: createShipment, add_package, NewDeliveryRoute. When they bring in an agent to add tracking features, the agent generates fetchTrackingInfo in one file and get_tracking_data in another, mimicking the inconsistency it found. The team stops, writes a naming guide (“use camelCase, use create/get/update/delete as CRUD prefixes, use domain terms from the glossary”), adds it to the agent’s context, and regenerates. The output is consistent on the first pass.

A solo developer working in a Rust project names a module utils. Three months later, that module has grown to contain logging helpers, string formatters, date parsers, and configuration loaders. When they ask an agent to add a retry mechanism, the agent puts it in utils because the name offers no guidance about what belongs there. Renaming the module forces a decision about what it actually contains, which leads to splitting it into logging, formatting, and config. The agent’s next task lands in the right module without being told.

Consequences

Good naming reduces the time every reader spends decoding intent. Code reviews focus on logic instead of asking “what does this variable mean?” New team members and new agents ramp up faster because the code is self-documenting at the identifier level. Consistency in naming also makes automated tools more effective: search, refactoring, and static analysis all depend on predictable identifier patterns.

The cost is attention. Choosing a good name takes longer than typing the first thing that comes to mind. Maintaining a naming guide requires discipline, especially when the domain evolves and old names no longer fit. Renaming is real work with real risk of breaking things, though modern tooling (and agents) can handle mechanical renames reliably if the codebase has good test coverage.

There’s a limit to what naming can achieve. A well-named function with a bad implementation is still broken. Names communicate intent; they don’t guarantee correctness. And naming conventions that are too rigid (“every variable must be at least 15 characters”) create their own readability problems. The goal is clarity, not compliance with an arbitrary length rule.

Related Patterns

• Uses / Depends on: Ubiquitous Language – the ubiquitous language provides the domain terms that names should draw from.
• Uses / Depends on: Domain Model – the domain model identifies the concepts that need names.
• Enables: Cohesion – well-named modules make it obvious when unrelated code has been grouped together.
• Enables: Harnessability – consistent naming is one of the structural properties that makes a codebase easier for agents to work in.
• Enables: Instruction File – a naming guide is a form of instruction file that shapes how agents write code.
• Contrasts with: Abstraction – naming makes things concrete and specific; abstraction hides specifics behind a generalized interface.

Sources

• Robert C. Martin codified naming as a design discipline in Clean Code (2008), Chapter 2: “Meaningful Names.” The principles in this article — describe what a thing represents, not how it’s implemented; be consistent within the codebase — trace directly to Martin’s treatment.
• Phil Karlton’s quip about naming being one of the two hard things in computer science (the epigraph above) is widely attributed but was passed down orally. It captures a truth that predates formal guidance: choosing good names is genuinely difficult because it requires understanding the domain, not just the syntax.

Further Reading

• Kevlin Henney, “Seven Ineffective Coding Habits of Many Programmers” (2016) – a talk that devotes substantial time to naming choices and their downstream effects on readability.