Naming things: a practical guide

Why naming dominates review, but rarely improves

Naming is easy to argue about and hard to practice. Reviews gravitate to it because it’s the first thing you notice when you read unfamiliar code.

The problem: most teams treat naming as taste, not a skill. People say “this name feels off” without a shared checklist for what better looks like.

Long term, that means:

This guide is deliberately practical. We’ll use three rules, work through real-feeling renames, and end with a short practice loop you can run on your own code this week.

Quick self-check: what’s your naming starting point?

Before rules, place yourself.

You’re probably in one of these modes:

• Label mode: you slap on the first name that compiles. Plenty of x, data, handleClick. You rely on comments to explain what’s going on.
• Vibe mode: you try to name things well but rely on feeling, not criteria. Reviewers often say “rename?” without clear guidance.
• Deliberate mode: you already pause to rename after code works. You still get stuck on bigger functions or cross-cutting stuff.

If you’re in label or vibe mode, focus hard on the examples and the first practice loop. If you’re already deliberate, skim for gaps, then jump to the refactor and AI sections to tighten your habits.

Rule 1: Say what, not how

A good name describes the observable job, not the internal trick.

Bad names latch onto implementation details that are likely to change. Good names describe the effect a caller cares about.

A name ages well when it tells the next reader what they get, not how today’s version happens to get it. Implementation details are cheap to change; caller expectations are expensive. Name the expectation.

Worked rename

// Before
function fetchAndFilter(arr: User[], term: string) {
  return arr.filter((u) => u.name.includes(term));
}

// After
function filterUsersByName(users: User[], nameQuery: string) {
  return users.filter((u) => u.name.includes(nameQuery));
}

What changed:

• fetchAndFilter → filterUsersByName: The function doesn’t fetch anything. The old name leaked an imagined caller flow, not the real job.
• arr → users: Callers care that these are users, not generic arrays.
• term → nameQuery: Now the parameter explains which field it targets.

The code didn’t change; only expectations became explicit.

When you’re stuck, finish this sentence out loud: “This function’s job is to…”. Your name should be a short version of that sentence’s verb + key nouns.

Rule 2: Prefer concrete to abstract

Vague names feel reusable. In practice, they just hide what’s really going on.

Abstract words (data, info, handle, process, manage) usually mean you haven’t decided what something actually is yet.

Worked rename

// Before
function handleData(input: any) {
  const result = doStuff(input);
  save(result);
}

// After
function enrichOrderWithPricing(order: Order) {
  const pricedOrder = calculateOrderTotals(order);
  saveOrder(pricedOrder);
}

Why this is better:

• handleData → enrichOrderWithPricing: The real job is “take an order and attach prices/totals”. That’s what future readers need to know.
• input → order, result → pricedOrder: You’ve named the domain, not the shape.
• doStuff → calculateOrderTotals, save → saveOrder: Each function now declares which concept it touches.

Concrete names feel narrower, but they let you see missing abstractions. If you later need to enrich something else, you can extract a reusable enrichWithPricing that works across entities (on purpose, not by accident).

Rule 3: Match the level of abstraction

The name should sit at the same altitude as the function’s body.

If the name sounds high-level but the body is a mess of details, callers feel tricked. If the name is gritty but the body just delegates, you leak internal structure.

Worked rename

// Before
function updateUser(id: string) {
  const user = usersRepo.find(id);
  user.lastLoginAt = new Date();
  usersRepo.save(user);
}

// After
function recordUserLogin(userId: string) {
  const user = usersRepo.find(userId);
  user.lastLoginAt = new Date();
  usersRepo.save(user);
}

Here, the function does one specific thing: it records a login. updateUser is much broader and creates false expectations.

Another common case:

// Before
function recordUserLoginAndSendWelcomeEmail(userId: string) {
  const user = usersRepo.find(userId);
  user.lastLoginAt = new Date();
  usersRepo.save(user);
  emailClient.sendWelcome(user.email);
}

// Two better options
function recordUserLogin(userId: string) { /* ... */ }
function recordUserLoginAndWelcome(userId: string) { /* ... */ }

Option A: split responsibilities and call two focused functions from a higher-level place. Option B: if this really is the smallest helpful unit, let the longer name expose both responsibilities.

Mismatch is a smell. If the body reads like a script, the name should too. If you only glue together two other calls, the name should describe the glue-level idea, not the innards of each call.

Bad patterns in the wild: utils, helpers, managers, processors

Certain words are magnets for confusion. They grow until they mean nothing.

Here’s how they usually show up, and what to do instead.

These words are not banned. They’re last resort labels once you’ve tried to name the real concept and failed.

If you must keep them (legacy code, shared libs), at least pair them with a domain word: EmailTemplateHelpers, ImageResizingUtils. That gives future you a better starting point when you eventually split things up.

Abbreviations: when they help, when they quietly hurt

Abbreviations are not evil. The problem is unsignaled, personal abbreviations.

In many codebases, you’ll see things like cfg, usr, req, res, ctx. Some of these are fine; some are slow traps.

Use this rule of thumb:

• If an abbreviation is standard in your language or framework, it’s usually okay: req/res in an Express handler, ctx in React or Next.js, err in Node callbacks.
• If it’s domain jargon that everyone on the team uses daily, it’s often fine: SKU, UUID, VAT.
• If you invented it just to save characters, it will hurt you later.

Compare:

// Harder to read
function calcPrRev(sku: string, qty: number) {
  const prc = getPrc(sku);
  return prc * qty;
}

// Clear enough
function calculateProjectedRevenue(sku: string, quantity: number) {
  const price = getPriceForSku(sku);
  return price * quantity;
}

The second is longer but not bloated. Each extra character pays for itself the first time someone else reads the file.

When in doubt, spell it out. You have autocomplete. Future readers don’t.

First practice loop: rename a real function

Let’s do an actual pass on your own code. Ten minutes, no architecture debates.

1. 1
   Pick a function you wrote in the last month, around 30-50 lines. Ideally something used in more than one place.
2. 2
   Write one sentence: “This function’s job is to…”. Don’t look at its current name while you do this.
3. 3
   Apply the three rules to just three things: the function name, its parameters, and 3-5 key variables.
4. 4
   Run tests or type checks to make sure you only changed names.

Example starting point:

// Before
function process(data: any) {
  const res = api.fetch(data.id);
  if (!res.ok) return null;
  const out = transform(res.payload);
  log(out);
  return out;
}

Attempted rename:

// After, first pass
function fetchAndTransformUserProfile(userId: string) {
  const response = api.fetch(userId);
  if (!response.ok) return null;
  const profile = transform(response.payload);
  log(profile);
  return profile;
}

We improved data to userId and res/out to response/profile. The function name is better, but still noisy and a bit how-ish.

On a second, more honest pass:

function loadUserProfile(userId: string) {
  const response = api.fetch(userId);
  if (!response.ok) return null;
  const profile = transform(response.payload);
  log(profile);
  return profile;
}

Now the name matches the level of abstraction: the caller cares that they can load a user profile, not that it “fetches and transforms”.

Reading feedback: good vs poor signals

Once you do that rename pass, pay attention to the feedback (from yourself and others).

Strong signals that the rename was worth it:

Weak signals, or signs you should retry:

• You need comments like // this actually only handles premium users because the name hides constraints.
• People suggest alternative names in review without agreeing on why yours is wrong or right.
• You still feel the need to open the function body to remember what it returns.

When feedback is vague (“this name feels off”), pull it into specifics: ask “what did you expect this to do from the name alone?”. Their answer is gold for your next rename.

Renaming as a refactor habit (and how to do it safely)

Renaming is one of the lowest-risk refactors you can do, if you keep the surface area small.

Here’s a simple protocol you can run in a live codebase in under ten minutes:

1. 1
   Scope it: rename one function or one concept at a time. No drive-by cleanups across the whole repo.
2. 2
   Use your tools: rely on language-aware rename (your IDE, Cursor, VS Code, IntelliJ) rather than text search, especially in TypeScript, Java, or C#.
3. 3
   Run checks: run tests, type-checkers, or at least build the project. In a Next.js app, for instance, npm test or npm run lint will flush out missed imports.
4. 4
   Scan the diff: read the diff like a stranger. Do the new names make the code read more like your mental model of the system?

If you don’t have tests, start with the most local functions (ones used in a single module). For critical flows, consider adding at least one basic test or logging check before renaming.

And don’t wait for perfect. The habit you want is: code works → quick pass to rename → then push. Two minutes now saves dozens of tiny puzzles later.

Working with AI: suggestions without outsourcing judgement

AI pair programmers are surprisingly good at generating name ideas. They’re also happy to suggest misleading names if your description is vague.

The trick is to use them as brainstorming partners, not oracles.

A simple pattern that works well in tools like Cursor, Claude Code, or GitHub Copilot Chat:

1. Describe behaviour first:

   This function takes a userId, fetches their profile from Supabase, normalizes it, and caches it for 5 minutes. Suggest 5 function names.
   

2. Ask for reasoning:

   Explain in one sentence why each name fits the behaviour.
   

3. Critique the answers like you would a teammate’s PR. If a name hides constraints (like caching) or over-emphasizes implementation (like Redis vs generic cache), push back:

   These focus too much on Redis. Suggest alternatives that a caller in another module would understand without knowing the caching layer.
   

You’ll know you’re over-trusting AI when you accept names you wouldn’t be able to defend in review. If you can’t explain why a suggested name is good using the three rules, it probably isn’t.