What you'll learn

  1. Quick answer
  2. Why it is worth caring about
  3. Rules that cover most cases
  4. Include units and the answer to 'which'
  5. Length should match scope
  6. Rename as soon as it is wrong
  7. FAQ

Quick Answer

Names should say what something is or does without needing a comment. Avoid abbreviations, name booleans as questions, use verbs for functions and nouns for values, and rename as soon as a name stops being accurate.

Why it is worth caring about

Naming sounds like a style preference and is not. Names are the primary interface between your code and the next person reading it, which is usually you in three months.

A good name removes work. Reading daysUntilDue requires no investigation; reading d requires tracing where it came from.

A misleading name is actively dangerous. A function called getUser that also writes to the database will eventually be called in a loop by someone reasonably assuming it only reads. That is a real bug caused entirely by a name.

The useful hierarchy: a misleading name is worse than a vague one, which is worse than a long accurate one. Length is the cheapest thing to sacrifice — editors autocomplete, and nobody has ever struggled to read code because a variable was too descriptive.

Rules that cover most cases

Reveal intent. The name should answer why it exists and what it holds.

d = 7                      # what is d?
daysUntilExpiry = 7        # clear

list2 = filter(users)      # what distinguishes it?
activeUsers = filter(users)

Booleans as questions, prefixed is, has, can or should:

if (status) { }            # status of what? true means what?
if (isPublished) { }       # unambiguous

Functions are verbs, values are nouns. calculateTotal() and total. A function named like a noun reads as though it is free to call, which encourages calling it repeatedly.

Avoid abbreviations except genuinely universal ones. usrMgr saves four characters and costs every reader a moment. id, url and http are fine because nobody hesitates.

Avoid meaningless words. data, info, manager, helper, utils, process. A class named DataManager tells you nothing — every class manages some data.

Include units and the answer to 'which'

A specific habit that prevents a specific class of bug.

timeout = 30           # seconds? milliseconds?
timeoutSeconds = 30    # unambiguous

distance = 5
distanceKm = 5

price = 199            # rupees? paise?
priceInPaise = 19900

Unit confusion causes real and expensive failures. Putting the unit in the name makes a mismatch visible at the call site, where setTimeout(timeoutSeconds) reads wrong if the function expects milliseconds.

The same applies to ambiguous scope. users in a function handling one organisation is unclear; usersInOrganisation or orgUsers is not.

And be consistent across a codebase. If one module says fetchUser, another getUser and a third loadUser for the same operation, readers must check whether the difference is meaningful.

Length should match scope

A useful rule that resolves most arguments: the wider the scope, the more descriptive the name.

A loop index used across two lines can be i. Everyone knows what it is and the entire context is visible.

for (let i = 0; i < items.length; i++) { ... }     // fine

A module-level constant used across twenty files needs to stand alone:

const MAX_LOGIN_ATTEMPTS_BEFORE_LOCKOUT = 5;

Similarly, a private helper in a small file can be shorter than a public exported function, which will be read by people with no surrounding context.

Short names in small scopes are not laziness — they are appropriate. The mistake is short names in large scopes.

Rename as soon as it is wrong

Names drift. A function called sendWelcomeEmail gains a notification and a database write, and the name is now a lie.

Two responses. Rename it to describe what it now does — or, better, notice that a function needing an inaccurate name is usually doing too much, and split it. Difficulty naming something is a design signal, and it is one of the most reliable ones available.

Renaming is cheap and safe with editor support. Use the rename-symbol command rather than find-and-replace, so scope is respected and unrelated matches are left alone — see VS Code setup.

Commit renames separately from behaviour changes. A diff mixing a rename across forty files with one logic change is unreviewable — see refactoring basics and pull requests.

The habit worth building: when you write a comment explaining what a variable holds, try making the name say it instead. Most of the time you can, and then the explanation cannot drift out of date.

Frequently Asked Questions

How long should a variable name be? Proportional to its scope. A two-line loop index can be i; a constant used across the codebase should be fully descriptive. Short names in wide scopes are the problem.
Is a misleading name worse than a vague one? Yes, considerably. A vague name makes readers investigate; a misleading one makes them confidently assume something false, which is how bugs are introduced.
Should I put units in variable names? Yes for anything ambiguous — timeoutSeconds rather than timeout. Unit mismatches are a recurring source of expensive bugs, and the name makes them visible at the call site.
What if I cannot think of a good name? That usually means the thing does more than one job. Difficulty naming is a reliable design signal, and splitting it often makes both names obvious.
Is renaming worth the diff noise? Yes, and keep it in its own commit. Names are how code is understood, and editor rename tools make it safe. Mixing a rename with a logic change is what makes the diff unreviewable.