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’sp, it could be anything. - Consistent names make suggestions consistent. If you call it
customerin one file andclientin another anduserin 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.jsbeatsutils2.js. Folders by purpose (components,data,tests) beat folders by date. - CSS classes.
.product-card__pricetells you where it belongs;.red-textdescribes 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
- Can someone guess what it does from the name alone?
- Are booleans phrased as questions?
- Are units clear?
- Do I use one word per concept?
- Would I understand this in six months?
- 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.
Related reading
Look at the last file you wrote. Which name would confuse you in six months?