On Naming Things

The two hardest problems in computer science are cache invalidation, naming things, and off-by-one errors. The joke is old but the naming problem isn’t.

I spent forty minutes last Tuesday naming a function. Forty minutes. The function itself took twelve minutes to write. It fetches a user’s notification preferences, cross-references them with their timezone, and returns a boolean: should we send this notification right now?

I started with shouldSendNotification. Too vague — send it where? Via what? Then isNotificationTimingValid. Better, but “valid” is a nothing word. Valid how?

Eventually I landed on isWithinNotificationWindow. Five words. Clear subject, clear predicate, clear domain. Someone reading this function name in a code review at 11 PM will know exactly what it does without clicking into it.

Why this matters

Names are the user interface of code. Every function, every variable, every module — someone will read its name and form an expectation. If the expectation matches the behavior, you’ve done your job. If it doesn’t, you’ve created a bug that no test will catch.

A misleading name is worse than a bad name. A bad name makes you look. A misleading name makes you assume.

The restaurant test

I have a test I apply to names. I call it the restaurant test. If you were explaining this code to someone at a restaurant — no screen, no IDE, just talking — would the name make sense?

“So this function checks if we’re inside the user’s notification window.”

That works. “This function validates notification timing” does not work at a restaurant, because your friend would immediately ask: “validates how?”

The restaurant test isn’t about simplicity. It’s about precision. The best names are precise enough that they don’t generate follow-up questions.

Forty minutes well spent.