An opinionated (and mainly correct) guide to naming

Naming has always been the joke problem in software, right up there with cache invalidation. But this piece treats it seriously, framing names as compression tools for your brain. The core claim: strong names let you hold more context in working memory, which makes reading unfamiliar code faster and debugging less painful. There's a stat backing this up too — clearer identifier names alone cut debugging time by 19%, and a separate study on LLM code comprehension found that improving identifier names delivered the single biggest boost to how well AI models understood a codebase.

The interesting twist here is where the advice points. Most style guides obsess over how you declare a function. This guide argues that's backwards, because call sites get read far more often than declarations do. So the trick is writing function calls that read like sentences — something like notify_all(registered_clients, about=the_new_version) — so a single line becomes one mental chunk instead of five things to track separately. The author borrows a technique from the old MIT classic Structure and Interpretation of Computer Programs called Wishful Thinking: write the code as if the ideal function already exists, get the sentence right, then go build the function to match.

A lot of the piece is really an argument against sloppy typing disguised as a naming lesson. The example of passing raw integers for both an RSS feed language and a clicked news article shows how primitive obsession quietly kills clarity — you can't tell intent from an int. Wrap those in proper domain types, the argument goes, and suddenly the variable names are freed up to explain why a value exists rather than just what type it is.

Then come the pet peeves. The I-prefix on interface names gets tossed out because whether something is technically an interface is the least useful fact about it. Getters and setters get roasted too — getCustomer and setCustomerStatus encourage code that asks permission instead of just telling an object what to do, versus something more direct like suspend(a_customer). And generic dumping-ground names like Utils or Helper get called out as an admission of design failure, a name so vague it invites more vague code to pile on top of it.

Underneath all the specific rules is one consistent idea: naming isn't decoration, it's a design decision that shapes the code that follows it. Vague names attract vague implementations, precise names constrain and clarify intent, and now that AI agents are reading and writing code alongside humans, that clarity has a second audience that benefits just as much as we do.