Naming Things in Code: Why It’s Hard and How to Do It Better

Hi there! I'm Maneshwar. Right now, I’m building LiveAPI, a first-of-its-kind tool for helping you automatically index API endpoints across all your repositories. LiveAPI helps you discover, understand, and use APIs in large tech infrastructures with ease.

Naming variables and functions is deceptively tricky for every developer.

We’ve all experienced it: staring at code, unable to remember if we called that counter count, num, or c.

Modern IDEs with autocomplete make it easy to lean on the editor to finish names for us, but this is a crutch.

Choosing good names is one of the hardest problems in programming.

Why Naming is So Hard

Naming feels hard because it requires precision in thought and empathy with future readers.

A name must capture the intent of the code and remain accurate even as code evolves.

You might ask yourself: Could this name be interpreted in ways I didn’t intend? Does it really describe what this value or function is for? These questions aren’t easy, and taking time to consider them is crucial.

In practice, you might find yourself deferring to autocomplete or placeholder names like foo when the perfect name doesn’t immediately come to mind.

But that only hides the underlying issue.

Good code requires stopping, reflecting, and choosing clear names upfront or refactoring them later.

Naming’s difficulty is well-documented.

Brief generic names (like x or temp) save keystrokes but cost clarity.

Overly long names can feel like overkill.

There’s no single right answer, which is why consistency and good sense are key.

The important thing is to be intentional: ask if a name fully describes what the code does. If it doesn’t, it’s a hint to rethink it.

Variables as Nouns

A clear rule of thumb is that variables hold data, so name them like data – as nouns or noun phrases.

In other words, a variable should sound like something, not an action. For example:

// Bad:
const x = 42
const total = calculate()

// Good:
const userAge = 42
const totalSales = computeTotal()

Here x or total tell you almost nothing, whereas userAge and totalSales immediately suggest what they represent.

This follows the principle that classes and data-holding entities are named like things (nouns).

A good name for a variable might be a single word (like count, price) or a compound noun (customerList, currentBalance). Avoid embedding verbs in variable names (e.g. use itemCount, not countItems).

Example: If you have a variable storing a user’s email, name it userEmail (a noun phrase), not emailAddressOfUser (too verbose) or getEmail (verb).

Descriptive, concise nouns make code self-documenting.

In fact, avoid meaningless placeholders altogether – names like foo, data, or temp should be replaced with something meaningful.

Functions (Methods) as Verbs

In contrast, functions and methods perform actions, so name them as verbs or verb phrases.

A function should read like an action or a command, possibly with an object. For instance:

// Bad:
function handle() { … }
function processItems(a, b) { … }

// Good:
function handleUserLogin() { … }
function calculateTotalPrice(items) { … }

The name doStuff or process is too vague.

Instead use a verb that says what the function does, and if helpful, to what.

Think of calculateTotalPrice as a tiny sentence: it performs the “calculate” action on “TotalPrice”.

This aligns with naming guidelines that recommend methods/functions be verb phrases.

It’s often helpful to include the object or concept being acted on: e.g. updateUserProfile tells you it updates a user profile.

Specificity here is better than brevity.

Likewise, don’t name a function after a noun if it does something.

For example, instead of function user(), use function getUser() or function fetchUser().

The verb at the start tells the reader there’s an action taking place.

Proper verbs in function names significantly improve readability and maintainability.

Positive Boolean Names

Boolean variables (flags) hold true/false values, so name them in a positive way.

Prefer names that read like affirmative questions or states (often starting with is, has, can): e.g. isEnabled, hasAccess, canDelete. This avoids confusion with negation. For instance:

// Bad:
const isNotVisible = true

// Good:
const isVisible = false

If you name something isVisible, then true clearly means visible.

If you called it isNotVisible, then you’d have to constantly mentally flip the meaning of true vs false.

In fact, one of the guideline warns that negative boolean names (isDisabled, isNotEnabled) lead to double negatives in code and extra cognitive load.

It suggests always using a positive name and inverting the logic if needed.

Tip: Use conventional prefixes like is, has, can or should for booleans (e.g. isActive, hasPermission, canEdit, shouldSave).

This makes the variable’s purpose clear.

By contrast, names like flag, done, or negated names (notReady) can be ambiguous.

In short, phrase booleans as positive statements: it reads more naturally (if (isActive) { … }) and avoids confusing negations.

Distinguishing Private (Member) Variables

In many languages, it’s helpful to mark private or member variables with a naming convention.

For example, in some codebases you might prefix private fields with an underscore (_count, _user) or m_ (m_count).

Other languages use keywords (like this. in JavaScript/PHP or private in Java) so a prefix isn’t strictly needed.

The goal is consistency and clarity.

Example: In Python it’s common to name a private attribute _buffer or __buffer to hint it’s internal.

In a C++/Java style, you might see int m_count; // m_ for member or simply this.count to differentiate.

Whatever convention you pick (underscore, m_, or something else), use it systematically to distinguish fields from local variables.

This small distinction prevents confusion between, say, a function parameter user and a class field _user meaning the same concept.

The key is consistency: pick one approach in your project or language community and stick with it.

Don’t mix styles (_count in one place and count in another) because that makes it hard to know which variables are private fields at a glance.

Descriptive Names Over Short and Vague Ones

It’s almost always better to use longer, more descriptive names than short, cryptic ones.

Be descriptive, not verbose.

A name like userProfileList is better than upl, and orderTimestamp beats ts.

Descriptive names serve as documentation and make code self-explanatory. For example:

// Bad:
const n = 5
const f = 3.14

// Good:
const numUsers = 5
const pi = 3.14        // PI is an exception: well-known constant

Short names like a, n, or data hide meaning and force readers to hunt for context.

This is why we emphasize naming for intent.

As one expert guide puts it, “apply names that conceptually describe what the identifier represents” and avoid meaningless names like foo, blah, or temp.

A variable called itemCount immediately tells you it’s counting items.

A function named calculateInvoiceTotal tells you exactly what it does.

When names are clear, reading code feels like reading plain language.

Sometimes very long names can be cumbersome to type. If a phrase is truly long, it’s okay to shorten it a bit for readability—just make sure it stays clear.

For instance, startDateOfEvent might be shortened to eventStartDate or just startDate if context is obvious.

The goal is to avoid ambiguity, not to minimize keystrokes.

Developers often joke that they spent hours debugging code only to realize a variable was misnamed – investing a few extra characters up front saves time later.

Even Winnie-the-Pooh knows: use clear names. This meme contrasts giving a descriptive name (good) versus overly compact or random names (bad). The random-gibberish example ("yeetus") is clearly a “what not to do” warning that clarity trumps brevity.

Case Styles and Naming Conventions

Pick a consistent casing style for multi-word names and use it everywhere. Common styles include:

• camelCase (e.g. userName, calculateTotalPrice) – often used in JavaScript, Java, C#, and many style guides for variables and functions.
• PascalCase (also known as UpperCamelCase, e.g. UserName, CalculateTotalPrice) – commonly used for class or type names in many languages.
• snake_case (e.g. user_name, calculate_total_price) – common in Python, Ruby, and C.

The specific style depends on your language or team's convention, but the rule is use one style and stick to it.

Mixing styles (like sometimes using total_price and other times totalPrice) is confusing.

One tip is to follow what the language community expects.

For example, Java methods and variables typically use camelCase, while Python variables use snake_case.

Whatever the convention, apply it consistently across your project. Using language-specific linters or formatters can enforce this automatically.

In summary, “use naming conventions of the programming language being used” – and do so uniformly for classes, functions, constants, etc.

Singular vs. Plural Names

A subtle but useful rule is to use singular names for single items and plural names for collections.

Think of whether a variable holds one thing or many.

If it’s one user object, name it user; if it’s a list of users, name it users.

Example:

• order (a single order object) vs. orders (an array or list of order objects).
• invoiceLine vs. invoiceLines.

This makes your code more intuitive.

When you see getUser(), you expect a single user.

When you see getUsers(), you know it returns multiple.

Some frameworks even assume this: for instance, RESTful APIs often use plural resource names (GET /users vs. GET /users/1).

A few cautions: Don’t be overly pedantic in every tiny context (e.g., std::vector<Order> users is fine, but std::vector<Order> userList is redundant).

The idea is clarity. And as one guide notes, once you pick a rule for singular/plural, be consistent with it throughout the codebase.

This consistency means less guesswork when reading or writing code.

Quick Naming Checklist

• Variables as nouns: e.g. userAge, totalPrice.
• Functions/methods as verbs: e.g. calculateTotal(), handleLogin().
• Boolean flags positive: e.g. isEnabled, hasItems (avoid negations like isNotReady).
• Mark private fields consistently (e.g. _count or m_count) so they stand out.
• Use descriptive names: avoid vague placeholders (foo, temp).
• Pick one case style (camelCase, snake_case, etc.) and use it project-wide.
• Use singular for single objects, plural for collections: e.g. item vs. items.
• Above all, be consistent. Decide on patterns and apply them everywhere.

Conclusion

Good naming isn’t just pedantry; it’s an investment in your code’s future.

Clear names act as comments, guiding anyone (including future you) through the logic.

Conversely, poor names cause confusion, bugs, and wasted time.

As one coding guide reminds us, it’s worth pausing to pick a good name or to rename when better options come to mind.

By treating names as first-class parts of your code’s design, you make maintenance smoother and collaboration easier.

Your IDE’s autocomplete is helpful, but real clarity comes from deliberate naming.

Thanks for reading, and happy coding — may your variables be clear and your functions well-named!

LiveAPI helps you get all your backend APIs documented in a few minutes

With LiveAPI, you can quickly generate interactive API documentation that allows users to search and execute APIs directly from the browser.

If you’re tired of manually creating docs for your APIs, this tool might just make your life easier.