The Weight of a Name

A short tutorial on writing code that teaches before it runs.

A name is your first line of design.
It tells the reader what to expect, what matters, and where not to get lost.

If the name misleads, the code breaks trust long before it breaks the build.

This guide explains real-world naming mistakes, better alternatives, and the reasoning behind them. Good names don't just make code readable.
They make it safe, testable, and worth maintaining.

What Makes a Good Name?

A good name does more than describe what something is.
It helps you decide what to do with it.

It answers the quiet questions every developer asks:

1. What is this?

2. Why is it here?

3. What can I safely expect it to do?

The clearer the name, the less second-guessing.
And the more confidence you build line by line.

Case 1: Vague Handlers

// ❌ Before function 
handleSubmit() { // handles login }

// ✅ After function 
submitLoginCredentials() { // clearly scoped, honest }

Why it matters:

"handleSubmit" does not specify an intent. It could validate input, call an API, update state, or redirect.

A good name does the explaining upfront. It saves teammates from guessing and tests from breaking.

Case 2: Meaningless Buckets

// ❌ Before 
const data = getData(); 
const result = process(data); 

// ✅ After 
const userProfile = fetchUserProfile(); 
const encryptedProfile = encrypt(userProfile);

Why it matters:

"data" and "result" mean everything and nothing.
They force readers to open implementation to understand the flow.

Names should carry shape, purpose, and meaning, especially when passed between layers.

Case 3: Misleading Booleans

// ❌ Before 
const isValid = user.age > 18; 

// ✅ After 
const isLegalAge = user.age > 18;

Why it matters:

Valid for what? When? According to which rule?

Good booleans tell the whole story in one glance.
They prevent silent logic drift.

Case 4: Hooks That Hide Meaning

// ❌ Before 
function useThing() { ... } 

// ✅ After 
function useUserContextState() { ... }

Why it matters:

Hooks often power complex states and behavior.
Vague names delay onboarding, block reuse, and hidden assumptions.

A good hook name works like a diagram. You can read it without clicking.

Case 5: Quiet Vulnerabilities

// ❌ Before 
function checkUser() { return user.isActive; } 

// ✅ After 
function hasVerifiedEmailAndPassword() { 
return user.emailVerified && user.hashedPassword !== null; 
}

Why it matters:

In security-critical paths, vague names mask real conditions.
"checkUser" sounds safe but what are we checking?

Precise names force alignment between code and consequence.

Case 6: Interface and Type Drift (TS-specific)

// ❌ Before 
type Status = "ok" | "fail" | "temp"; 

// ✅ After 
type AuthStatus = "authenticated" | "unauthenticated" | "expired";

Why it matters:

Interfaces and enums outlive their modules. Generic names like "status" hide domain purposes.
A good name scopes risk and intention to the domain it serves.

Naming Traps You Can Avoid

Names like temp, thing, or flag don't tell the reader anything useful.
Use something like sessionTimeout or modalRef names that point to what the value is.

Don't hide meaning behind data or info
These are shapeless. They force the reader to dig.
Say userPayload or hasAccess instead. Let the name carry context.

Be specific with function names
getData() tells us nothing.
fetchUserSettings() tells us what's coming back and from where.

Avoid verbs without context
check() and process() are too generic to be useful.
Use names like checkUserAuth() or mergeDraftIntoUserState(), and they reveal logic and intention.

Naming rule of thumb
If you have to explain a name, rewrite it.
The best names don't need backup. They speak for themselves.

Naming at Scale

In shared codebases, names become interfaces.
What you name today may be used, abused, or misunderstood by people outside your team.

Use the domain's real language.
Write names that teach.
Avoid cleverness that ages poorly.

Some of the best ideas on naming come from books like Clean Code and The Pragmatic Programmer. They don't offer rules to memorize. They offer reminders worth returning to:

• Use names that reveal intent.

• Don't call something a list if it's a set.

• Use verbs when something does work. Use nouns when they hold value.

• Don't repeat yourself in names. If it's a user, we know it's an object.

• And above all, stay consistent. Clever fades. Clarity lasts.

A good name won't just compile. It will hold up when the code gets tested, reviewed, and rewritten. That's how you know it's right.

Final Thought

Bad names create hesitation.
Good names create flow.

Every clear name is one less comment.
One less bug.
One less confused teammate.

Write names that teach.
Let your code stay quiet.