Names That Can't Be Misunderstood

The Mars Climate Orbiter crashed in 1999. Cost: $327 million. Cause: one team used metric units, another used imperial. The software didn't make the distinction clear.

Ambiguous names cause bugs. Not "might cause." Cause.

The Ambiguity Test

For every name you write, ask: "Could someone reasonably interpret this differently than I intended?"

If yes, the name is dangerous.

filter — Keep or Remove?

const filtered = users.filter(u => u.banned);

Does filtered contain banned users or non-banned users?

In JavaScript, filter keeps items that return true. So this keeps banned users. But the name "filtered" suggests removed.

Better:

const bannedUsers = users.filter(u => u.isBanned);
const activeUsers = users.filter(u => !u.isBanned);

Now there's no ambiguity.

clip — Start or End?

clip(text, length);

Does this remove from the beginning or the end? Does it keep length characters or remove length characters?

Better:

truncateFromEnd(text, maxLength);
// or
keepFirst(text, characterCount);

check — Returns What?

if (checkPermission(user)) { ... }

Does checkPermission return a boolean? Throw an exception? Log something? The name doesn't tell you.

Better:

if (hasPermission(user)) { ... }  // Clearly returns boolean
assertHasPermission(user);        // Clearly throws

Boundary Names: min/max, begin/end, first/last

These word pairs have specific meanings. Use them correctly.

min/max

Use for inclusive limits:

const MIN_PASSWORD_LENGTH = 8;   // 8 or more
const MAX_ITEMS_PER_PAGE = 100;  // 100 or fewer

begin/end

Use when begin is inclusive and end is exclusive (like array slices):

text.slice(beginIndex, endIndex);  // beginIndex included, endIndex excluded

first/last

Use when both are inclusive:

const firstDayOfMonth = 1;
const lastDayOfMonth = 31;

Danger: Inconsistent Usage

If your codebase uses max to mean "exclusive upper bound" in one place and "inclusive upper bound" in another, you have a bug factory.

Pick conventions. Document them. Enforce them.

Boolean Naming

Booleans should read like yes/no questions.

Use Standard Prefixes

Avoid Negatives in Names

// Bad: Double negatives are confusing
if (!isNotEnabled) { ... }

// Good: Positive names
if (isEnabled) { ... }

Name the True Condition

// Bad: What does "checked" mean here?
const checked = validateEmail(input);

// Good: Clear meaning
const isValidEmail = validateEmail(input);

Words with Multiple Meanings

Some words are especially dangerous:

get

In some codebases, get means "return from memory." In others, it means "fetch from network." In others, it has side effects.

Be explicit:

• getFromCache vs fetchFromApi
• readSetting vs loadSetting

set

Does setActive(true) change local state or persist to database?

If it persists: saveActiveStatus(true) or updateActiveState(true)

render

Does render return a string? Write to DOM? Return a component?

Be specific: renderToString, renderToDOM, createComponent

The Reader Test

Before committing code, do this:

1. Read each name in isolation, without looking at surrounding code
2. Ask: "What would a new team member think this means?"
3. If there's any ambiguity, rename it

This takes 30 seconds. It prevents hours of debugging.

Real-World Bug Example

I once saw this bug in production:

function processExpiredSessions(sessions) {
  return sessions.filter(s => isExpired(s));
}

The developer thought processExpiredSessions would handle expired sessions (delete them, log them, etc.). Instead, it just returned them.

A customer's session was never cleaned up. They saw another user's data.

If the function had been named getExpiredSessions, the bug would have been obvious during review.

Key insight: Ambiguity is debt with hidden interest. Every ambiguous name is a future misunderstanding, a future bug, a future 3am incident. Invest the extra 10 seconds to find a name that can't be misunderstood.