← Back to Code & Alchemy

Naming Things

The actual hardest problem in computer science. Not cache invalidation, not off-by-one errors, the name you give a variable at 2pm on a Tuesday and live with for the next three years.

Why This Is Actually the Hard Problem

A bad name doesn't break the build. It compiles fine, passes every test, ships to production, and quietly costs everyone who touches that code afterward a few extra seconds of "wait, what does this actually do." Multiply that by every read of the codebase for the next few years and a lazy name is one of the most expensive things you can leave behind, precisely because nothing ever forces you to fix it.

Name the Thing, Not the Type

`userList`, `dataArray`, `itemObj` describe the container, not what's inside it. The type is already right there in your editor's hover tooltip, it doesn't need to live in the name too. `activeSubscribers`, `pendingOrders`, `flaggedComments` tell you what the variable is for the moment you read it, without opening the file it came from.

Booleans Should Read Like Questions

`isReady`, `hasPermission`, `canRetry` read naturally in an if-statement: `if (isReady)` versus `if (ready)`, which could just as easily be a status string. The prefix costs you three characters and saves the next reader from guessing the type. This one's cheap enough that there's no real excuse to skip it.

Functions Are Verbs, Always

A function that isn't named as an action is a function whose purpose you have to infer from context. `validate`, `fetchUser`, `normalizePhone` tell you exactly what happens when you call them. `userValidation` or `phoneHelper` tell you a topic, not an action, and you end up opening the function body just to find out what it actually does.

Consistency Beats Cleverness

Pick `fetch` or `get` for retrieval and use it everywhere, don't mix `fetchUser` with `getOrder` with `retrieveInvoice` in the same codebase. The specific word matters less than picking one and sticking with it, since a consistent vocabulary lets people predict a name before they've even seen it, which is most of what good naming is actually for.

When a Name Is Hard to Find, Listen to That

Struggling to name something cleanly is frequently a signal the thing itself is doing too much. A function called `processAndValidateAndSaveUser` is a naming problem wearing a design problem's clothes, it's really three functions pretending to be one. If you can't land on a clean, honest name in under a minute, that's usually worth treating as a design smell, not just a wording exercise.

Building The Habit

Rename on sight the moment a variable name stops matching what it holds, don't leave it for a future refactor that may never come. It costs seconds now and confusion later if skipped. A good name is a tiny act of respect for whoever reads this code next, and there's a real chance that person is you, six months from now, with zero memory of writing it.

← Back to Code & Alchemy