Naming things so you can still find them

Names are the index of a project you did not write

When you write code yourself, you remember where things are. When a model writes it, the names are the only map you have. A project with inconsistent names is one you cannot search, and searching is how you read a codebase you did not write.

This is not tidiness. It is the difference between finding the overlap rule in ten seconds and asking the model where it is, getting a wrong answer, and writing a second one.

One word per concept, everywhere

Decide whether the person paying you is a customer, a client or a user, and then never use the other two. In the database column, in the variable, in the file name, in the button, in your prompts.

What happens otherwise is specific and common: the table is customers, one file talks about clients, a route is /api/users, and now searching for any one of them finds two-thirds of the code. Worse, the model reads whichever file it happened to open and continues in that dialect, so the drift compounds.

Keep a short glossary in your rules file:

Customer — a person who books. Never client or user.
Stylist  — a person who performs services. Never staff or employee.
Booking  — one appointment. Never reservation or slot.
Slot     — an available time, not a booking.

Five lines, and the vocabulary stops moving.

Conventions that stop arguments

The specific convention matters far less than having one. Pick these and write them down:

• Database tables and columns in snake_case, plural tables: bookings, starts_at.
• JavaScript variables and functions in camelCase: startsAt, findFreeSlots.
• React components in PascalCase, one per file, filename matching the component: BookingCard.tsx.
• Booleans read as questions: isCancelled, hasPaid. Never flag, never status2.
• Timestamps end in _at: created_at, cancelled_at. Durations name their unit: duration_minutes.

That last one prevents a real bug. A field called duration will be filled with minutes in one place and seconds in another, and the code that divides by sixty will be somewhere else entirely.

The names to refuse

data, info, item, thing, handleClick2. They carry no information, and a model will produce them when it does not know what something is. A variable called data is a small sign that the code around it was written without understanding.

utils.ts and helpers.ts. These become the drawer where everything unclassifiable goes. Within a month it is 600 lines of unrelated functions and nobody can find anything. Name files after what they do: dates.ts, money.ts, slots.ts.

Manager, Service, Handler with nothing else. BookingManager tells you nothing that bookings.ts does not.

Anything with New, 2, Final or Old in it. formatDateNew means there are two, one of them is wrong, and both are probably still being called. When you see this, delete one immediately or you will debug the wrong file next Tuesday.

The duplicate check

Ask for this occasionally, and act on the answer:

List every function in this project that formats a date or a price.
For each, say which files call it. If two do the same job,
say which one to delete.

Generated codebases accumulate near-duplicates because each request is answered in isolation. Two date formatters differing by a comma is harmless. Two overlap checks differing by whether a booking ending at 14:30 blocks one starting at 14:30 is a bug that reproduces intermittently and will take you a full afternoon.

Rename early, while it is free

The day you notice a name is wrong is the cheapest day to fix it. A rename across four files is a two-minute agent task and a clean diff. The same rename across forty files is an afternoon and a risk.

Use your editor’s rename rather than search-and-replace where you can: VS Code’s F2 understands the language and will not rename a string in a comment or a similarly-named variable in an unrelated file. Then read the diff, because a rename touching files you did not expect means the name was used somewhere you did not know about, and that is worth knowing.