Naming Conventions in Code: Why Names Matter More

Naming in code covers the names of variables, functions, files, tables and fields. Naming conventions are the rules a team agrees on for choosing them. It all seems trivial until you’re trying to work out how data differs from data2, and why handleClick charges a credit card.

Code is read far more often than it’s written. A good name saves time on every read; a bad one costs time on every read. When an AI writes and reads the code, the stakes go up: the assistant has no memory of your project, so names are its main clue to what lives where and what it does.

Why it matters even more with AI

Someone who has worked on a project for six months remembers that process() in helpers.ts actually sends the customer an invoice. An AI assistant doesn’t. It sees the name and draws conclusions from it.

Hence the familiar vibe-coding problems:

• the assistant can’t find an existing function because it’s named differently from what it searched for, so it writes a new one;
• it edits the wrong one of two similar functions;
• it uses a status field with one meaning when the table next door uses it for something else.

Good names work as documentation you can’t forget to update, because it’s in the code itself.

Naming conventions that work

Name by meaning, not by type. users beats array, unpaidInvoices beats list. A name answers “what is this”, not “how is it stored”.

Functions are verbs. sendInvoice, getActiveProjects, cancelSubscription. The name should say what the function does and, above all, whether it changes anything. getUser shouldn’t create a user when one doesn’t exist.

Booleans are questions. isPaid, hasAccess, canEdit. Then conditions read like sentences: if (user.canEdit).

Event handlers describe the action, not the gesture. handleClick tells you nothing. submitOrder or openPaymentDialog tells you everything.

Units go in the name. timeoutMs, priceCents, durationDays. A good share of money and time bugs come from one part of the code thinking in dollars and another in cents.

One concept, one word. If the product has customers, don’t call them customer in one place, client in another and buyer in a third. Pick a word and use it everywhere: in code, in the database, in how the team talks.

No junk suffixes. New, Old, 2, Final, Temp signal a duplicate nearby. If the new version replaced the old one, delete the old one and give the new one a proper name.

No dumping grounds. Files called utils, helpers, common or misc quickly become where everything without a home ends up. A function that formats prices belongs in pricing or format-price, not utils.

How long should a name be

Short names are fine where the scope is small: i in a three-line loop confuses nobody. The further a name travels and the more places use it, the more descriptive it should be. A function called from twenty files deserves a three-word name.

The opposite extreme is getAllActiveNonDeletedUsersWithPaidSubscriptionFromDatabase. If a name doesn’t fit in your head, the function probably does too much.

Style conventions

camelCase, snake_case, PascalCase: your language and framework have usually made this choice already. Follow whatever your ecosystem expects, and switch on a linter so nobody has to police it by eye. Consistency is what counts. A project where half the files are user-card.tsx and half are UserCard.tsx confuses people and tools alike.

The database is a special case: table and column names are the most expensive to change, because migrations, backups and other people’s integrations depend on them. Spend five extra minutes on them.

Renaming what you already have

Don’t rename the whole project in one go. Use your editor’s “Rename symbol” refactoring, which updates every place the name is used rather than every place the text happens to match. Each rename is its own commit with nothing else in it. Start with the most misleading names: functions whose name promises one thing while they do another.

Then write the conventions into your AI assistant’s instructions: which words mean which concepts, which suffixes are banned. Assistants follow written rules noticeably better than they guess.

In short

• Naming in code is the main clue for both people and an AI that has no memory of your project.
• Name by meaning; functions are verbs, booleans are questions, units go in the name.
• One concept, one word across the project; no New, no 2, no utils dumping grounds.
• The more widely a name is used, the more descriptive it should be.
• Rename with editor tooling, in separate commits, starting with the most misleading names.

If the names in your project have drifted apart, SUBXCAT can help bring them back in line without stopping development.