Write the Docs Portland 2017: Even Naming This Talk Is Hard by Ruthie BenDor

Naming in software is hard because names are guesswork that must fit human mental models—and when they miss, the damage shows up as confusion, frustration, and avoidable technical debt. Ruthie BenDor frames naming as one of the two “hard problems” in computer science (alongside cache invalidation), then argues that the real issue isn’t just cleverness or taste. Software is built largely by extending and amending other people’s work, so every new abstraction arrives with a name that becomes the “sticky note” on the filing system in someone’s head. If that label doesn’t map cleanly to what the abstraction does—or clashes with a reader’s context—people don’t just misunderstand; they start doubting their own competence and stop trusting the codebase.

Several concrete examples illustrate how naming fails when teams reuse words without respecting the meaning they carry. In one story, an events product avoids the heavy feel of “event” by calling them “invites,” only to end up with an email method that sends “invites” to people who have been “invited to an invite.” In another, Redux’s “containers” collide with a waste-hauling industry where “dumpster” is a loaded term; the result is a concept that feels obvious to one domain and jarring to another. BenDor also points to the broader problem of descriptive naming: reducing a complex concept to a single word inevitably drops nuance, and the name then evokes unknown assumptions in readers who may not share the same context.

She adds that naming mistakes persist because teams often don’t experience the pain directly. Bad names can become an empathy failure (“it doesn’t affect me”), a beginner’s mind failure (the author forgets what it was like not to understand), or a localization failure (people don’t recognize that the term carries emotional or cultural baggage). She cites “blacklist” and “blocklist” as an example where “neutral” technical terminology can still trigger strong connotations, and notes that standards bodies have moved toward “allow lists” and “block lists.”

Beyond emotional and contextual issues, BenDor argues that the first name is often wrong because teams don’t yet know the abstraction’s essence. She uses a Hitchhiker’s Guide to the Galaxy analogy: like a whale materializing in an impossible place, early projects make do with provisional names while the real shape of the work emerges. That guesswork is also why technical debt and refactoring are unavoidable: only after building do teams learn what the software is meant to do and whether the naming—and the design behind it—fits.

So what makes a name “good”? BenDor treats it as a balancing act and a judgment call: names shouldn’t be too long or too short, should follow style guides, avoid unnecessary ambiguity, and should be easy to pronounce and memorable without being misleading. Good names create “aha moments” by connecting an abstract concept to something tangible and setting correct expectations. Tools can help with mechanics—searching for collisions, enforcing style, catching inconsistencies—but they can’t replace the human judgment required for the hard part. Her closing message is practical: developers should treat naming as part of the craft, documentarians should flag missed marks, and everyone should remember that a bad name isn’t personal—it’s an opportunity to improve shared understanding.