Blog / Build with AI /

Naming things in code: why AI needs good names too

Ask a developer what the hardest part of programming is and, sooner or later, you’ll hear the joke: naming things. It’s a joke because it’s true. A good name tells you what something is and does. A bad one makes you read the whole function to find out.

When you build with AI, naming matters twice. Humans read your code later, and the AI reads it too. A model reading data2 and temp has to guess. A model reading unpaidInvoices and calculateLateFee has real context, and its suggestions get better.

Why names matter more than you think

Code is read far more often than it’s written. Each time you open a project after a break, you’re a stranger to it. Names are the first thing you see.

Compare these two snippets:

function f(a, b) {
  return a.filter(x => x.d < b);
}
function overdueInvoices(invoices, today) {
  return invoices.filter(invoice => invoice.dueDate < today);
}

Both do the same thing. Only one explains itself. The second also gives an AI model enough information to correctly extend it: “add a function that finds invoices due within seven days” is obvious from the vocabulary.

Why AI needs good names too

A language model doesn’t understand your project the way you do. It sees text, and it predicts what fits. Your names are the strongest clues about meaning.

  • Clear names reduce wrong guesses. If a variable is called price, the AI may assume it’s a number in your store’s currency. If it’s p, it could be anything.
  • Consistent names make suggestions consistent. If you call it customer in one file and client in another and user in a third, new code may mix all three.
  • Names carry your intent into new chats. When you paste a snippet into a fresh conversation, the names are most of the context you’re providing. Working on a project over many AI chats shows how fragile context can be.
  • Good names make AI explanations better. Ask “what does this do?” of readable code and you get a good answer. Ask of cryptic code and you get a guess.

Rules of thumb for good names

1. Say what it is, not how it’s stored

customerList is okay. customers is usually better. arr1 is unhelpful.

2. Use verbs for actions, nouns for things

Functions do something: calculateTotal, sendReminder, loadProducts. Variables hold something: total, reminderDate, products.

3. Booleans should read like a question

isActive, hasStock, canEdit. When you read if (hasStock), it sounds like plain English. flag and status2 don’t.

4. Be specific enough, not wordy

data says nothing. productData is better. productDataFromSupplierFile is probably too much unless you really have several kinds. Aim for the shortest name that can’t be confused with its neighbour.

5. Pick one word per concept, and stick to it

Decide: is it a customer or a client? A post or an article? A remove or a delete? Then use it everywhere. Mixed vocabulary is a quiet source of bugs and confusion.

6. Include units where it helps

timeout could be seconds or milliseconds. timeoutMs leaves no doubt. weight is vague; weightKg isn’t.

7. Avoid abbreviations unless everyone knows them

url and id are fine. cstmrAcctBal isn’t. Saving four characters isn’t worth the confusion.

8. Avoid misleading names

If getUser also saves the user, the name lies. A function should do what its name says, and only that.

Beyond variables: names everywhere

The same thinking applies outside code:

  • Files and folders. invoice-helpers.js beats utils2.js. Folders by purpose (components, data, tests) beat folders by date.
  • CSS classes. .product-card__price tells you where it belongs; .red-text describes appearance, which will go out of date the moment the design changes.
  • Database tables and columns. Names stick for years. Choose with care.
  • Commit messages and log entries. “Fix bug” tells nobody anything. “Fix overlap check when leave starts and ends on the same day” does.
  • Prompts. Calling the thing you’re building by one clear name throughout a chat helps the model stay on track.

Using AI to improve names

AI is useful for the renaming pass, as long as you stay in charge.

Review this code and suggest clearer names for variables and functions. List each suggested rename with a one-line reason. Don’t change the behaviour and don’t output the full code yet.

Then you decide. Accept the ones that clarify; reject the ones that over-explain. Once you’ve picked, ask it to apply them, and run your tests or try the page again afterwards. A rename that misses one occurrence breaks the code. Editors have a “rename symbol” feature that updates every use safely, and it’s often safer than pasting a rewritten file.

You can also set the vocabulary up front:

In this project, we call a person who buys something a “customer”, never “user” or “client”. An order has “lineItems”. Use this vocabulary in all code you write.

That small glossary at the start of a chat is one of the best ways to keep generated code consistent. It also works well in a build log, as described in keeping a build log while working with AI.

Names and comments

Good names reduce the need for comments, but they don’t replace them. Comments explain why; names explain what. “Retry three times because the supplier’s server is slow” is a useful comment. “Add one to i” is not. See also prompting for clean, readable code.

A quick naming checklist

  1. Can someone guess what it does from the name alone?
  2. Are booleans phrased as questions?
  3. Are units clear?
  4. Do I use one word per concept?
  5. Would I understand this in six months?
  6. Would an AI reading only this snippet know what it’s for?

Key takeaways

  • Names are the first thing humans and AI read.
  • Use nouns for things, verbs for actions, questions for booleans.
  • Pick one word per idea and keep it everywhere.
  • Include units and avoid cryptic abbreviations.
  • Use AI to suggest names, then verify after renaming.

FAQ

Are long names bad?

Not if they’re clear. Short names are only good when they can’t be misunderstood.

Should I rename old code?

Yes, when you’re already working in it and have tests or can check it. Don’t rename everything at once.

Does it matter for tiny scripts?

Less, but scripts have a habit of growing. It’s cheaper to name well from the start.

Look at the last file you wrote. Which name would confuse you in six months?