Variable Naming Rules: Write Code Anyone Can Read

The names you choose for variables, functions, and classes determine whether your code reads like documentation or like a puzzle. No technical skill has a higher return on readability than naming, and most developers significantly underinvest in it. This guide covers the rules, patterns by identifier type, common mistakes with their fixes, and a practical test you can apply to any name before committing it to the codebase.

Jump to a section

Why naming matters Rule 1: Reveal intent Rule 2: Precise, not just long Rule 3: Be searchable Rule 4: Avoid disinformation Naming variables Boolean prefixes Naming functions Naming classes Naming constants Case conventions Context and scope Common mistakes The naming test 7-step refactoring guide FAQ

Why Naming Matters More Than You Think

Code is read far more often than it is written. Research consistently puts the ratio at 5:1 or higher: for every minute you spend writing code, five to ten minutes are spent reading it, whether your own code or someone else's. Every minute invested in choosing a clear name pays back in every future reading of that code.

5:1

Read-to-write ratio: code is read 5x more than it is written

Comments needed when a variable name clearly reveals its intent

30 sec

Time to rename a variable well, preventing minutes of confusion for every future reader

The comparison below is the clearest demonstration of why naming is worth taking seriously:

Hard to read

function calc(d, r) {
  return d * (1 - r);
}

Immediately understandable

function calculateDiscountedPrice(
  originalPrice,
  discountRate
) {
  return originalPrice * (1 - discountRate);
}

Version A is shorter. Version B is immediately understandable without context, without documentation, and without running the code. Anyone reading Version B knows what it does, what inputs it expects, and what it returns. That is the entire argument for good naming.

If you need a comment to explain what a variable holds or what a function does, the name failed. The fix is not to add the comment. The fix is to rename.

The Four Fundamental Rules of Good Naming

Names Should Reveal Intent

A name should answer: what does this hold? What does this do? What does this represent?

The most important rule. A name that requires context or a comment to understand is a bad name. Someone reading a single line of code in isolation should be able to understand its purpose from the names used in it.

Reveals nothing

const d = new Date();
const t = user.tasks
  .filter(t => t.done);
const x = calculateTotal(items);

Reveals intent

const currentDate = new Date();
const completedTasks = user.tasks
  .filter(task => task.isCompleted);
const orderTotal = calculateTotal(lineItems);

Be Precise, Not Just Long

Long vague names are worse than short precise ones. Length alone is not clarity.

A name's quality is measured by how precisely it describes what it holds or does, not by how many characters it contains. Adding words like "data", "info", "list", or "object" to a name without adding meaning makes the name longer and no clearer.

Long but vague

const dataList = [];
const userInformation = {};
const processResult = null;
const responseData = await fetch(url);

Precisely named

const pendingOrders = [];
const billingAddress = {};
const paymentAuthorisationCode = null;
const userResponse = await fetch(url);

Use Searchable Names

Single-letter variables and cryptic abbreviations cannot be found with a codebase search.

A variable used in many places across a large codebase needs to be findable. Searching for s in any codebase returns thousands of irrelevant results. Searching for isUserActive returns exactly what you need. Single-letter variables are acceptable for counters in tight loops by convention only. Everywhere else, use a searchable name.

Unsearchable

const s = user.status === 'active';
const n = items.length;
const e = order.estimatedDelivery;
const p = user.permissions;

Searchable

const isUserActive = user.status === 'active';
const itemCount = items.length;
const estimatedDeliveryDate = order.estimatedDelivery;
const userPermissions = user.permissions;

Avoid Disinformation

Names that suggest the wrong type, size, or purpose are actively harmful.

A name that misleads is worse than a vague name. If a variable named userList holds a single object, every developer reading it will waste time wondering why the list has no array methods. If a variable named processData holds a boolean, the mismatch between the name's suggestion and the reality creates confusion that costs real debugging time.

Misleading names

// Suggests array, is a single object
const userList = { id: 42, name: "Alex" };

// Suggests a function, is a boolean
const processData = true;

// Ambiguous abbreviation
const hp = 100; // health points? horsepower?

Accurate names

// Single object — use singular noun
const currentUser = { id: 42, name: "Alex" };

// Boolean — use prefix
const isProcessingEnabled = true;

// Explicit, unambiguous
const playerHealthPoints = 100;

Naming Patterns by Identifier Type

Different kinds of identifiers play different roles in code. Matching the grammatical form of the name to the role of the identifier makes code read like well-structured prose rather than a sequence of arbitrary labels.

Variables Use nouns camelCase

// Values — descriptive nouns
const userName = "Alex";
const orderTotal = 149.99;
const maxRetries = 3;

// Collections — plural nouns
const users = [];
const pendingOrders = [];
const activeConnections = new Set();

Functions Use verbs camelCase

// Actions — verb + noun
function getUserById(id) { }
function calculateOrderTotal(items) { }
function sendPasswordResetEmail(user) { }

// Event handlers
function handleFormSubmit(event) { }
function onPaymentSuccess(payment) { }

Classes Use nouns PascalCase

// Concrete nouns — what it IS
class UserProfile { }
class PaymentProcessor { }
class ShoppingCart { }

// Errors — always extend Error
class ApiError extends Error { }
class ValidationError extends Error { }

Constants Use nouns SCREAMING_SNAKE

// Application constants
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = 'https://api.example.com';
const JWT_EXPIRY_SECONDS = 3600;
const DEFAULT_PAGE_SIZE = 20;
const STRIPE_API_VERSION = '2024-01-01';

Boolean Naming: Always Use a Prefix

Booleans deserve special attention because a poorly named boolean is impossible to read without knowing its context. A variable named user could be many things. A variable named active is ambiguous. A variable named isUserActive is unmistakably a boolean that describes whether the user is active.

The standard prefix conventions for booleans make the variable's nature and purpose clear at the point of use:

Current state

isLoggedIn
isLoading
isValid
isExpired
isVisible

has

Possession or completion

hasPermission
hasError
hasChildren
hasActiveSubscription

can

Capability or permission

canEdit
canDelete
canPublish
canAccessAdmin

should

Conditional behaviour

shouldRetry
shouldRedirect
shouldShowModal
shouldSendEmail

did / was

Past state or action

didSubmit
wasSuccessful
didUserConfirm
wasCacheHit

JavaScript — boolean naming in practice

// Variables
const isLoggedIn        = user.sessionToken !== null;
const hasPermission      = user.roles.includes('admin');
const canEdit            = isLoggedIn && hasPermission;
const shouldRetry        = attempts < MAX_RETRY_COUNT;

// Functions that return booleans — same prefix convention
function isEmailValid(email)          { return /.../.test(email); }
function hasActiveSubscription(user)   { return user.plan !== 'free'; }
function canUserEdit(user, document)   { return user.id === document.authorId; }

Naming Functions: Verbs That Describe Actions

Functions do things. Their names should describe what they do using a strong action verb followed by the object being acted upon. A well-named function call reads like an English instruction: calculateOrderTotal(lineItems), validateEmailFormat(email), sendPasswordResetEmail(user).

JavaScript — function naming patterns

// CRUD operations — verb is explicit about the operation
async function fetchUserById(userId) { }
async function createOrder(orderData) { }
async function updateUserProfile(userId, updates) { }
async function deleteExpiredSessions() { }

// Transformations — verb describes what changes
function formatCurrency(amount, currency) { }
function convertCelsiusToFahrenheit(celsius) { }
function parseQueryString(url) { }
function sortUsersByLastName(users) { }

// Event handlers — handle/on prefix makes the trigger clear
function handleFormSubmit(event) { }
function handleKeyboardShortcut(event) { }
function onPaymentSuccess(paymentIntent) { }
function onConnectionError(error) { }

⚠ Avoid verbs that hide what a function actually does

Functions named process, handle, manage, or doStuff communicate almost nothing. These names are often a sign that the function does too many things and should be broken up into smaller, more focused functions each with a specific, describable purpose. If you cannot name a function's action clearly, that is often a signal that the function needs to be refactored, not just renamed.

Naming Classes: Nouns That Represent Concepts

Classes represent things or concepts: entities, data structures, services, and abstractions. Name them with nouns in PascalCase. The name should communicate what the class is, not what it does.

Verb-like or too generic

class ProcessOrders { }
class HandleAuthentication { }
class DataManager { }
class Utility { }
class Helper { }

Concrete nouns

class OrderProcessor { }
class AuthenticationService { }
class UserRepository { }
class PaymentGateway { }
class EmailNotifier { }

A class named DataManager tells you almost nothing. A class named UserRepository tells you exactly what it represents: the access layer for user data. Prefer the most specific, concrete noun that accurately describes what the class models. Error subclasses should always end in Error so they are immediately recognisable when thrown or caught.

Naming Constants: SCREAMING_SNAKE_CASE

Constants are values that are set once and never change. The SCREAMING_SNAKE_CASE convention makes constants immediately distinguishable from variables at the point of use, signalling to every reader that this value is fixed, not computed at runtime.

JavaScript — constants in practice

// Application limits
const MAX_RETRY_COUNT      = 3;
const MAX_FILE_SIZE_MB     = 10;
const DEFAULT_PAGE_SIZE    = 20;
const SESSION_TIMEOUT_MS   = 30 * 60 * 1000;

// API configuration
const API_BASE_URL         = 'https://api.example.com/v2';
const STRIPE_API_VERSION   = '2024-01-01';
const JWT_EXPIRY_SECONDS   = 3600;

// Magic numbers replaced with named constants
const POINTS_PER_DOLLAR    = 10;
const FREE_SHIPPING_THRESHOLD = 50;

// Usage — the constant name explains the number's meaning
const loyaltyPoints = orderTotal * POINTS_PER_DOLLAR;
const isFreeShipping = orderTotal >= FREE_SHIPPING_THRESHOLD;

💡 Replace magic numbers with named constants

A "magic number" is a literal numeric value in code with no explanation of its meaning. if (attempts > 3) leaves readers guessing. if (attempts > MAX_RETRY_COUNT) is self-explanatory. Every literal number that appears more than once in a codebase, or that would require a comment to explain, should be extracted to a named constant. Use the Case Converter to convert any constant name to SCREAMING_SNAKE_CASE instantly.

Case Convention Reference

Different languages and contexts have different conventions. The table below covers the most common identifier types across JavaScript, Python, and general programming:

Identifier Type	Convention	Example	Language Context
Local variables	camelCase	orderTotal, isLoggedIn	JavaScript, TypeScript, Java
Local variables	snake_case	order_total, is_logged_in	Python, Ruby, Rust, Go
Functions / methods	camelCase	calculateTotal(), getUserById()	JavaScript, TypeScript, Java
Functions / methods	snake_case	calculate_total(), get_user_by_id()	Python, Ruby, Rust
Classes	PascalCase	UserProfile, PaymentProcessor	All languages universally
Constants	SCREAMING_SNAKE	MAX_RETRIES, API_BASE_URL	All languages universally
Private fields	_camelCase	_internalState	JavaScript (convention only)
URL slugs / CSS classes	kebab-case	user-profile, order-total	HTML, CSS, URLs
Database columns	snake_case	user_id, created_at	SQL databases universally
JSON API fields	camelCase or snake_case	userId or user_id	Convention varies by API

Context Reduces Necessary Name Length

A name's clarity depends not just on the name itself but on the context in which it appears. A well-named class, function, or module provides context that makes the names inside it shorter without losing clarity. This is an important counterbalance to the rule about being precise: you do not always need to repeat the surrounding context in every name inside it.

JavaScript — context provides meaning

// Inside a class called UserAuthentication:
class UserAuthentication {
  // 'validateCredentials' is enough — no need for 'validateUserCredentials'
  validateCredentials(email, password) { }

  // 'generateToken' is enough — context makes 'authentication token' clear
  generateToken(user) { }

  // 'isExpired' is enough inside an auth class — it's clearly the auth token
  isExpired(token) { }
}

// Inside a function processing orders:
function processOrders(orders) {
  return orders.map(order => ({  // 'order' is fine — context is clear
    id:    order.id,
    total: calculateTotal(order.items)  // 'calculateTotal' not 'calculateOrderTotal'
  }));
}

The class name provides the namespace. Names inside a well-named scope can be shorter because the outer name already supplies the context. The skill is knowing when the context makes a shorter name clear and when a name that appears in many different contexts needs to be more explicit to remain unambiguous.

The Most Common Naming Mistakes

These mistakes appear in codebases at every experience level. Each one has a recognisable pattern and a straightforward fix:

Using the type as the name

Names like string, array, object, or number describe the type, not the content. The reader already knows the type from the value or the TypeScript annotation.

Bad

const string = "Hello";
const array = [1, 2, 3];
const obj = { name: "Alex" };

Good

const greeting = "Hello";
const userIds = [1, 2, 3];
const currentUser = { name: "Alex" };

Over-abbreviating

Abbreviations save keystrokes during writing but cost comprehension during every future reading. The trade is almost never worth it outside of universally understood conventions like i for loop index.

Bad

const usrMgr = new UserManager();
const authTkn = generateToken();
const cfg = loadConfiguration();

Good

const userManager = new UserManager();
const authToken = generateToken();
const config = loadConfiguration();

Meaningless prefixes

Words like data, info, object, and value add length without adding meaning. If removing the suffix leaves the name clearer, it should be removed.

Bad

const userData = { name: "Alex" };
const userInfo = { name: "Alex" };
const responseData = await fetch(url);

Good

const user = { name: "Alex" };
const billingProfile = { name: "Alex" };
const searchResponse = await fetch(url);

Inconsistent conventions

Mixing naming conventions within the same codebase forces readers to context-switch constantly. Every identifier should follow the same convention as other identifiers of the same type.

Bad — mixed conventions

const user_name = "Alex";
const userAge = 28;
const UserEmail = "[email protected]";

Good — consistent camelCase

const userName = "Alex";
const userAge = 28;
const userEmail = "[email protected]";

The Five-Question Naming Test

Before committing any identifier name, run it through this test. If all five questions get a yes, the name is good. If any get a no, rename before moving on.

Apply to every variable, function, and class

Five questions that determine whether a name is good

Does it reveal intent?

Someone reading only this line understands what it holds or does, without needing to read the surrounding code or any comments.

Is it pronounceable?

You can say it out loud in a code review without hesitation. Names that cannot be spoken are usually a sign they are not clearly conceptualised.

Is it searchable?

You can find every use of this identifier in the codebase by searching for the name. Single letters and common words fail this test immediately.

Does it avoid disinformation?

It does not suggest the wrong type (a list name for a single object), wrong size, or wrong purpose. It does not use abbreviations that mean different things to different people.

Is it consistent with the rest of the codebase?

It follows the same convention as other identifiers of the same type. If similar variables use camelCase, this one does too. If similar functions use a get prefix, this one does too.

7-Step Guide to Improving Naming in an Existing Codebase

If you are working in a codebase with poor naming conventions, improving it systematically is more effective than trying to fix everything at once:

Start with new code, not old code. Apply good naming to every new function, variable, and class you write today. Do not get blocked trying to fix everything at once before writing new features. Build the habit with new code first.
Rename while you work in an area. When you open a file to fix a bug or add a feature, rename the worst identifiers in that file before making your change. This is the Boy Scout Rule: leave the code slightly better than you found it. Small, consistent improvements accumulate into a significantly better codebase over time.
Use your IDE's rename refactoring, not find-and-replace. Every modern IDE (VS Code, IntelliJ, WebStorm) has a rename refactoring that updates every reference to an identifier safely across the entire codebase. Use it. Find-and-replace misses references in dynamic contexts and renames things it should not.
Document your naming conventions in a style guide. Write down the conventions your team follows: camelCase for variables, PascalCase for classes, is/has/can for booleans, verb-noun for functions. A short team style guide prevents the mixed conventions that make codebases hard to read. Use the Case Converter as a quick reference for converting between formats when you need to match an existing convention.
Apply the five-question naming test in code review. Make naming a standard part of your code review checklist. Asking "does this name reveal intent?" in a PR is a low-friction way to improve naming across the team without a big refactoring effort. Most naming improvements happen in seconds during review.
Eliminate magic numbers by extracting named constants. Search your codebase for literal numeric values that appear more than once or that need context to understand. Extract each one to a named constant at the top of the file or module. This is one of the highest-impact, lowest-risk naming improvements available in an existing codebase.
Use the Text Diff Checker when renaming across backend and frontend. When a field name or function name changes on the backend (for example from user_id to userId in a JSON response), use the Text Diff Checker to compare the old and new API response shapes side by side. This ensures every field that needs updating in the frontend is visible before you start modifying code.

Frequently Asked Questions About Variable Naming

How long should a variable name be?

As long as it needs to be to reveal its intent precisely, and no longer. There is no fixed character limit. A name like i is perfect for a loop counter. A name like calculateDiscountedPriceAfterCouponApplication is probably too long because it suggests the function does too many specific things. The practical sweet spot is names that are specific enough to be unambiguous in context but short enough to read comfortably in a code expression. Most good names are between 8 and 25 characters. Anything much shorter risks vagueness. Anything much longer usually signals that the concept needs to be simplified.

Is it acceptable to use i, j, k for loop variables?

Yes, for simple numeric loop counters in tight loops where the variable does nothing but count iterations. for (let i = 0; i < items.length; i++) is universally understood. But when the loop variable represents a meaningful concept, name it accordingly: for (const user of users) is clearer than for (const u of users), and items.forEach((item, index) => ...) is clearer than items.forEach((x, i) => ...). The convention applies to the counter, not to the item being iterated.

What is the difference between camelCase, PascalCase, snake_case, and kebab-case?

These are naming conventions that differ in how words are separated and capitalised. camelCase (also called lower camelCase) starts lowercase and capitalises each subsequent word: orderTotal. PascalCase (also called UpperCamelCase) capitalises every word including the first: OrderProcessor. snake_case uses underscores as word separators with all lowercase: order_total. SCREAMING_SNAKE_CASE uses underscores with all uppercase: MAX_ORDER_TOTAL. kebab-case uses hyphens as separators with all lowercase: order-total. Use the Case Converter to convert any string between all of these formats instantly.

When should I use comments vs better naming?

Almost always, better naming is preferable to comments. A comment that explains what a variable holds or what a function does is a code smell: it means the name failed its primary job. However, comments are appropriate for explaining why code does something (the reasoning or business context), for documenting non-obvious performance trade-offs, for referencing external resources like RFCs or bug tracker issues, and for legal or license text. The heuristic: comments that say "what" or "how" are usually signs of bad naming. Comments that say "why" are often genuinely valuable.

How do I handle naming when translating between different layers with different conventions?

Different layers of an application often have different naming conventions: a Python backend uses snake_case, a JavaScript frontend uses camelCase, a SQL database uses snake_case, and a JSON API response might use either. The key principle is to follow each layer's native convention rather than spreading one layer's convention into another. Use a transformation step at the boundary: a serialiser on the backend converts snake_case database fields to camelCase JSON, and the frontend reads camelCase. Use the Case Converter to quickly convert field names between formats when you are building or reviewing these boundary mappings.

Should function parameters follow the same naming rules as variables?

Yes, completely. Parameters are variables with a specific scope (the function body) and they appear at the callsite as well as inside the function. A well-named parameter makes the function call read clearly: sendEmail(recipientAddress, subject, body) communicates far more than sendEmail(a, s, b). Parameters also document the function's interface: someone reading calculateDiscount(originalPrice, discountRate) understands what to pass without reading the function body or external documentation. Name parameters with the same care as any other variable, applying reveal-intent, precision, and the boolean prefix conventions when relevant.

Free browser-based developer tools

Tools for working with names and conventions

Convert any string between camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE, and kebab-case instantly. Compare code changes, format JSON responses, and generate slugs. All free, all in your browser.

Cc Case Converter → # Slug Generator → ≠ Text Diff Checker → { } JSON Formatter → ⇄ JSON to YAML → ⇄ JSON to XML →

Good Names Are the Cheapest Documentation You Will Ever Write

Every variable, function, and class name you write is a piece of documentation that lives directly in the code. It is read every time that code is opened, reviewed, or debugged. A good name costs 30 seconds to choose and pays back minutes of comprehension time on every future reading. At a 5:1 read-to-write ratio, that investment compounds continuously.

The four rules cover the majority of naming decisions: reveal intent, be precise not just long, use searchable names, and avoid disinformation. The five-question naming test applies them in practice. The identifier-type patterns (nouns for variables, verbs for functions, PascalCase nouns for classes, SCREAMING_SNAKE for constants) provide the grammatical structure that makes code read naturally.

Use the Case Converter whenever you need to move a name between conventions, and the Text Diff Checker when renaming fields that cross the boundary between your backend and frontend. Both tools make the mechanical side of naming faster so you can focus on the conceptual side: finding the name that reveals exactly what you mean.

Menu

Pages

Tools

Variable Naming Best Practices : Write Code Anyone Can Read

Why Naming Matters More Than You Think

The Four Fundamental Rules of Good Naming

Naming Patterns by Identifier Type

Boolean Naming: Always Use a Prefix

Naming Functions: Verbs That Describe Actions

Naming Classes: Nouns That Represent Concepts

Naming Constants: SCREAMING_SNAKE_CASE

Case Convention Reference

Context Reduces Necessary Name Length

The Most Common Naming Mistakes

The Five-Question Naming Test

7-Step Guide to Improving Naming in an Existing Codebase

Frequently Asked Questions About Variable Naming

Tools for working with names and conventions

Good Names Are the Cheapest Documentation You Will Ever Write