The Psychology of Naming Things in Code

In partnership with

Welcome back to Nullpointer Club, where we decode the hidden forces that shape software engineering. Today’s topic is one every developer complains about, yet rarely examines deeply: naming.

Ask any engineer what the hardest problems in programming are, and you’ll hear a familiar joke:

“There are only two hard things in computer science: cache invalidation and naming things.”
The joke persists because it’s true. Naming is deceptively simple on the surface — it’s “just picking a word,” after all — but it carries enormous cognitive weight. A good name shapes how code is understood. A poor name creates friction, ambiguity, and long-term maintainability costs.

Let’s break down why naming is psychologically hard, and why its impact on engineering quality is so underrated.

1. Naming Requires Accurate Mental Models

(And Most of Us Don’t Fully Have Them Yet)**

When naming a function or variable, you must carry a complete mental model of what it does, why it exists, how it changes over time, and how others will use it. That demands clarity — something that often doesn’t exist in early stages of implementation.

This mismatch creates tension:

• You don’t yet fully understand the domain.

• Requirements shift.

• Responsibilities evolve.

So naming becomes a moving target.

Often, poor names signal not just sloppy writing, but muddy thinking. If you can’t name something well, you probably don’t understand it well.

2. Naming Forces You to Compress Concepts Into Small, Precise Labels

A name is a compression algorithm.

It shrinks the entire purpose, behavior, and scope of something into a few characters — and that’s cognitively difficult. This is why we often see unhelpful abstractions like:

doStuff()
data
process()
helper()

These names fail because they compress too much and communicate too little. Good naming requires the opposite: communicate intent with surgical clarity.

3. Our Brains Prefer Familiar Patterns, Even When They Are Wrong

Developers often fall back on generic names because they’re mentally available. System 1 thinking (fast, instinctive) defaults to vague patterns like:

• “Manager”

• “Util”

• “Controller”

• “Handler”

But these names create category overload. When everything is a “Manager,” nothing is.

Good naming requires System 2 thinking: slower, deliberate analysis about structure and intent. That’s uncomfortable, so we often avoid it.

4. Naming Shapes How Future Developers Interpret Code

(And Misinterpretation Is Expensive)**

Names guide expectations. Designers call this “affordance.” Code has affordances too.

Consider a function named:

get_user()

Does it:

• fetch from cache?

• fetch from DB?

• fetch from API?

• create user if missing?

• throw an exception?

• return null?

The ambiguity forces readers to open the implementation, breaking flow. Multiply that by dozens of names across thousands of lines, and you have a maintainability nightmare.

A clearer name like:

fetch_user_from_db()

removes guesswork and prevents mental context switching. Naming is a human factors problem, not a syntactic one.

5. Poor Naming Encourages Incorrect Use

(Good Names Create Guardrails)**

Two different types of misuse typically arise from weak naming:

Accidental misuse

Because the name didn’t signal constraints, side effects, or expectations.

Structural misuse

Because the name didn’t communicate architectural boundaries.

For example:

Update()

If this function also performs validation, logging, and API calls, then the name doesn’t warn the reader about side effects. Good naming not only informs — it disciplines.

Practical Principles for Better Naming

Naming is difficult, but it’s not mystical. Here are principles that consistently improve readability and maintainability:

1. Prefer clarity over brevity

Short names are not a virtue if they hide meaning.

2. Name by intent, not mechanics

Focus on why, not just what.

Bad:

sortUsers()

Good:

rankUsersByLastLogin()

3. Avoid overloaded generic words

“handle,” “manage,” “process,” “util,” and “helper” are cognitive junk drawers.

4. Keep names consistent with domain language

Use the vocabulary the business or system uses.

5. Refactor names as understanding evolves

Naming is not a one-time act — it should be revised as clarity improves.

6. Match naming scope to responsibility

A highly specific function should have a highly specific name.

Naming: The Small Thing That Shapes Big Systems

Great engineering teams treat naming as part of design, not decoration. The cost of a bad name compounds every time another developer reads it, uses it, or misinterprets it. The cost of a good name compounds too — in clarity, onboarding ease, and long-term maintainability.

Naming feels hard because it forces three high-level skills at once:

• Deep understanding

• Abstraction

• Communication

It’s not just a technical act; it’s a cognitive one.

In the end, code is for humans first and machines second. Machines don’t care what we name things. But humans pay for naming mistakes every day.

And that’s why naming remains one of the hardest — and most important — skills in software engineering.

See you next week,

— Nullpointer Club Team