Published on
|
6 min read

How to Name Variables So Your Team Doesn't Hate You: The Definitive Guide

We've all been there. You open a pull request, eager to review a new feature, only to find yourself squinting at a variable named tempData2. Or worse, a loop where the iterator is j3. You spend the next twenty minutes playing detective, trying to figure out what that "temp data" actually holds.

Variable naming is often dismissed as a "soft skill" or a matter of preference. But in reality, it is one of the most critical technical skills a developer can master. In this guide, we’ll explore how to name variables so your team doesn't just tolerate your code—they actually enjoy reading it.

Why Variable Naming Matters (The Silent Cost of Technical Debt)

Code is read far more often than it is written. When you write a variable name, you aren't just telling the compiler where to store data; you are communicating intent to a human being. Research suggests that developers spend up to 70% of their time reading and understanding code. If your naming is poor, you are directly stealing time from your colleagues.

Bad naming leads to:

  • High Cognitive Load: Teammates have to hold a "translation map" in their heads to remember what x1 and x2 represent.
  • Logic Bugs: If isUserActive is actually checking if the user is admin, someone will eventually break the logic during a refactor.
  • Onboarding Friction: New developers will take twice as long to contribute if they can't follow the data flow.
  • The "Hate" Factor: Code reviews become frustrating instead of productive.

A Step-by-Step Framework for Naming Anything

If you're stuck staring at a blinking cursor, follow this 3 step logic to find the perfect name.

Step 1: Identify the "What"

Ask yourself: What does this data represent? Not what type it is, but what its role is in the business logic.

  • Example: Is it a list of users? Or is it specifically a list of Inactive Users to be Deleted?
  • Bad: users
  • Better: inactiveUsers

Step 2: Define the "Context"

Does the name need more info to avoid confusion?

  • If you have an ID, is it a userID, orderID, or productID?
  • Pro Tip: Avoid redundant context. If you are inside a User class, don't name the variable userEmail. Just use email.

Step 3: Choose the "Part of Speech"

  • Nouns for objects/variables: totalPrice, customerName.
  • Verbs for functions: calculateTotal, sendEmail.
  • Adjectives for Booleans: isVisible, isProcessing.

The Golden Rules of Clean Code Principles

1. Be Descriptive, Not Cryptic

A 20-character name that explains everything is infinitely better than a 2-character name that explains nothing. Modern IDEs handle the typing for you; don't sacrifice clarity for brevity.

Bad:

const d = 86400; // time?
const r = getUsr(u.id);

Good:

const SECONDS_IN_A_DAY = 86400;
const currentUser = getUserById(user.id);

2. Avoid Mental Mapping

If a reader has to remember that s stands for account_status, you’ve failed. The only exception is traditional loop counters like i, j, and k in very small scopes (under 5 lines).

3. Use Pronounceable Names

If you can’t discuss your code in a meeting because the variable names are unpronounceable (mod_tmstmp_val), it’s a bad name. Use modificationTimestamp.


Specialized Naming Cases (The "Expert" Level)

1. Booleans: The "Question" Pattern

Boolean variables should sound like a true/false question. Use prefixes like is, has, can, or should.

  • Bad: active, permission, login, valid
  • Good: isActive, hasPermission, isLoggedIn, isValidInput

2. Event Handlers: Action vs. Reaction

In UI development, distinguishing between the action and the handler is crucial.

  • Action: handleClick
  • Reaction (Prop name): onClick
  • Specific: submitFormHandler or onEmailChange

3. Error Handling: Clarity in Crisis

When naming errors, don't just use e or err.

  • Bad: catch(e) { console.log(e); }
  • Good: catch(connectionError) { retryConnection(connectionError); }

4. Constants and Configuration

Use SCREAMING_SNAKE_CASE for global constants. This signals to other developers that this value is immutable and should not be changed.

const MAX_RETRY_ATTEMPTS = 5;
const API_BASE_URL = "https://api.v1.com";

Consistency: The "Ubiquitous Language"

Nothing confuses a team more than using three different names for the same concept.

  • Fetch vs. Get vs. Retrieve: Pick one. Don't use fetchUser in one file and retrieveUser in another.
  • Manager vs. Processor vs. Service: If you use PaymentService, don't name the next one OrderProcessor.

Naming Traps to Avoid (The "Hate List")

  • Numbered Variables: data1, data2, tmp3. If you need numbers, you probably need an array or better descriptions.
  • The "Data" Trap: Everything is data. userData is okay, but data by itself is meaningless.
  • Abbreviations: Is msg a Message or a Monosodium Glutamate? Use message.
  • Enconding Types: nameString, userArray. Let your type system (like TypeScript) do this work.

Standard Conventions by Language

  • camelCase: JavaScript, TypeScript, Java, C#.
  • snake_case: Python, Ruby, PHP, SQL.
  • PascalCase: Classes and React Components across most languages.
  • kebab-case: CSS classes and URL slugs.

FAQ: Common Questions on Variable Naming

Should I use short names for small scopes?

Yes, for extremely short scopes (like a one-line map function), u => u.id is fine. For anything else, use user => user.id.

How do I name "temp" variables?

Avoid the word temp at all costs. Instead, name it based on its state. For example, use sanitizedInput instead of tempInput.

What if the name is too long?

If a name is over 35 characters, it might mean the variable is doing too much or your scope is too broad. See if you can simplify the logic first.

Conclusion: Naming is an Investment

Naming things well takes extra time upfront. It requires you to stop and think: "What does this actually represent?" But that small investment pays massive dividends in the form of reduced bugs and faster development.

The next time you’re about to name a variable data, take five seconds. Ask yourself what that data is. Your team and your future self will thank you.


Mustafiz Kaifee

Mustafiz Kaifee

@mustafiz_kaifee
Share