1. NAMING SOFTWARE
A RANT MEDITATION ON
?!
Ruthie BenDor / @unruthless
Howdy, everyone! I am just absurdly excited to rant — I mean meditate — with you all today // on the
topic of naming things in software. // I have been wanting to give this talk for literally years, as my long-
suffering friends will attest, so this is gonna be fun. // Before we get to names in software, let’s start
with my name.

2. RUTHIE
Ruthie BenDor / @unruthless
@unruthless
I’m Ruthie. // I’ve spent over a decade writing software, rewriting software, and sometimes even writing
about rewriting software. // Quick show of hands: Who here is not an engineer? Awesome, I think you’ll
get a kick out of some of the examples from behind the engineering curtain today. // Let’s get into it.

3. “THERE ARE ONLY TWO
HARD PROBLEMS IN
COMPUTER SCIENCE:
CACHE INVALIDATION AND
NAMING THINGS.”
Phil Karlton
http://blog.modernmechanix.com/machine-solves-hard-problems
Ruthie BenDor / @unruthless
If you work with or around software, you may have heard or read this truism: That there are only two hard problems in
computer science, and those two problems are cache invalidation, and naming things. // As a side note, if anyone else has
feelings about cache invalidation, (a) welcome to my life, and (b) come find me at the bar later. // I’m starting with this truism
because it’s, well, true, but also because there’s an amended version.

4. “THERE ARE ONLY TWO
HARD PROBLEMS IN
COMPUTER SCIENCE:
CACHE INVALIDATION,
NAMING THINGS,
AND OFF-BY-ONE ERRORS.”
Leon Bambrick
http://blog.modernmechanix.com/machine-solves-hard-problems
Ruthie BenDor / @unruthless
Here’s the amended version. I share this amended version not because it’s a good joke, though it is. I
share the amended version because its existence nicely illustrates this essential fact about modern
software development: much of what we make is an amendment to, or an extension of, or otherwise
built with or atop something created by someone else.

5. https://www.prodataloggers.com http://matt.might.net/articles/phd-school-in-pictures/
circle containing all human knowledge
Ruthie BenDor / @unruthless
That’s true, right? Unless your company lawyers have told you to write a clean-room implementation of
something, or unless you’re doing doctoral-level research at the very boundaries of the field,
mainstream software development these days is largely an exercise in making things with other
people’s code.

6. http://http://gooddogsoftware.com/
Ruthie BenDor / @unruthless
And if we’re always making things with other people’s code, well, that implies that we’re all going to be
spending much of our working lives learning about and getting to know projects, products, and tools
that are brand-new to us.

7. https://medium.com/@yegg/mental-models-i-find-repeatedly-useful-936f1cc405d
Ruthie BenDor / @unruthless
When a project or product or tool or method is new to me, and I’m getting to know it, my very first task
is to build up my mental model of it. I want to understand how it connects with what I already know.

8. “EVERY TIME I LEARN
SOMETHING NEW, IT
PUSHES SOME OLD
STUFF OUT OF MY
BRAIN.”
Homer Simpson
https://www.planetclaire.tv
Ruthie BenDor / @unruthless
And let’s be real, what I’m really doing is determining if this new thing will be good enough at solving
my problem to justify the space it’ll take up should I choose to bring it into my project and/or brain. So:
what’s the very first piece of information that we have about this new abstract construct that we’re
getting to know?

9. Ruthie BenDor / @unruthless
https://www.davidseah.com
Its name. Its name is the sticky note on the side of the shoebox amongst the eternity of shoeboxes
that comprise my brain’s filing system. So names are pretty important.

10. http://lifehacker.com/the-only-technique-to-learn-something-new-1709323497
Ruthie BenDor / @unruthless
But sometimes names don’t give us enough of a clue or any clue which shoebox to put this thing in!
And sometimes we make things that other people are trying to cram into their virtual toolkits and
mental shoeboxes, and you know what they’re thinking?

11. ಠ_ಠ
Ruthie BenDor / @unruthless
‘What even is this’, and ‘What do I do with this’, and ‘Am I dumb?’ and ’I have no idea where this goes.’

12. 1. WHY IS IT HARD TO NAME SOFTWARE?
3. WHAT MAKES A NAME GOOD OR BAD?
2. WHY DO BAD NAMES PERSIST?
4. HOW CAN WE NAME SOFTWARE BETTER?
Ruthie BenDor / @unruthless
So as people who use software and people who write software and people who write about software,
we ought to take care to name things well. So that’s what I’m going to talk about today. Names within
software, why they matter, why they sometimes are not great, and what we can do to make them
better.

13. 1.
WHY IS IT HARD TO
NAME SOFTWARE?
Ruthie BenDor / @unruthless
First. Why is it so hard to name software?

14. BECAUSE THE GOOD NAMES ARE
ALREADY TAKEN.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
Let’s start with a cynical reason: that all the good names are already taken. // We’ve kept things pretty
abstract until now, so let’s get specific for a bit. // Let’s go through an exercise of creating and
documenting some software together.

15. https://blog.hubspot.com/marketing/organize-to-do-list#sm.00001thnyt36uycvcs1fmdszd6elp
I keep a daily to do list. It’s the next piece of paper in this spiral bound notebook that I carry around,
and I like the checked paper because it makes it easier for me to draw literal check boxes which I can
then check off which makes me feel happy and productive even when the words next to the box say
‘brush my teeth’. Don’t judge, we’ve all been there.

16. ?
https://blog.hubspot.com/marketing/organize-to-do-list#sm.00001thnyt36uycvcs1fmdszd6elp
Let’s say I’m getting sick of carrying this around when I’m also always carrying (**HOLD UP
SMARTPHONE**) this around. How hard can it be to reproduce this functionality and recreate this
experience in code? // Famous last words.

17. Thanks, GitHub.
Okay, I’m creating this app. First thing I’m gonna do is set up my git repository. GitHub recognizes that
naming is hard, and tries to help in an adorable way, but no, I need an awesome external-facing name
for this product. ‘To-do Lists’? Boring but serviceable, just let me check to make sure there isn’t already
something out there with that name….

18. Crap. Not only is there something out there with exactly that name, there is also something out there for
every other name that I can come up with.

19. Now, if I were a marketer or a brand strategist, this would meander off into a discussion of naming
products. And there’s definitely interesting things to talk about there, but we’ve only got half an hour, so
rather than talk about bad names for software, let’s focus more on bad names within software.

20. BECAUSE THE GOOD NAMES TERMS ARE
ALREADY TAKEN OVERLOADED.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
It turns out that naming WITHIN software has the same problem as naming OF software. But rather
than refer to this problem using normal words like normal people, we instead like to be clever and use
the word ‘overloading’, which does have a specific meaning in computer science, to be fair, but it’s
really unnecessary here. Some real world examples.

21. A friend works at a company that is trying to make it easier for people to plan and hold events. // They found that calling an
event ‘event’ felt too heavy to their users, like too much of a commitment, and they wanted to keep it light. So they decided
to call events ‘invites’. You get invited, to an invite. In the code, there’s a function that sends out emails letting people who
have been invited know that they’ve been invited. Those emails are also called invites. // To recap: there’s a method that
sends invites to people who have been invited to an invite.

22. Another example. I work on a codebase that uses a framework called React and a library called Redux. The only important
thing to know is that when using Redux, there’s this core concept of containers, it’s a way to organize your application logic.
The company I work for makes software for trash haulers, people who empty dumpsters for a living. // That industry really
hates the word ‘dumpster’. It’s like saying ‘The Googles’ to someone who works in tech, nonironically. It just grates. You
know what they call them? Containers.

23. The containers circled in red, on the left there, has absolutely nothing to do with every single instance
of the word ‘container’ circled in green. That definitely didn’t confuse me for about a month and a half.

24. CONTAINERCEPTION
http://imgur.com/Gp41aN6
Ruthie BenDor / @unruthless
Oh and the best part is that the way that I run this entire codebase on my laptop? Inside a Docker —
wait for it — container.

25. BECAUSE NAMING IS REDUCTION,
AND WE ARE BAD AT CHOOSING WHAT TO EXCLUDE.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
Okay, let’s move on to another reason why naming software is hard. Descriptive naming is hard
because it’s reductive, and we’re bad at choosing what to leave out. It is not possible to convey the
totality of meaning and implication of an abstract construct in a single word, and yet that’s what we’re
doing every single time we name a variable, or class, or API method.

26. InternalFrameInternalFrameTitlePaneInternalFr
ameTitlePaneMaximizeButtonWindowNotFocuse
dState
http://www.pushing-pixels.org/2007/11/07/and-the-longest-jre-class-name-is.html
Ruthie BenDor / @unruthless
I’m going to repeat myself because it’s obvious that the Java runtime environment didn’t hear me: It is
not possible to convey the totality of meaning and implication of an abstract construct in a single word,
so stop trying. // We’ll get into what makes a good name later, but a good rule of thumb should be
doesn’t line-wrap twice.

27. BECAUSE NAMES EVOKE,
AND WE ARE BAD AT ANTICIPATING WHAT.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
All right, another reason why naming software is hard. The name you give something will evoke
unknown things for the reader, and as an industry we are horrifyingly bad at anticipating the kinds of
things that the names we choose will evoke. We get this weird collective tunnel vision and fail to
appreciate that others may have different contexts. The following examples range from questionable to
appalling.

28. Ruthie BenDor / @unruthless
Cockroach DB. It’s actually a good name in one sense, that it evokes survivability of your data, which is
their core value proposition. // But I ask you: Would you be likely to consider using this product if
you’ve ever had to deal with a roach infestation? How happy would you be using this product if you’re
currently dealing with one? // Let’s go back to names within software.

29. Ruthie BenDor / @unruthless
So, there’s this model of communication where one process has one-way control over other processes.
This is a really common best-practice architecture in database replication, where there is one
authoritative database instance with control over some replicas that are synced to it. Know what this is
usually called?

30. MASTER
SLAVE SLAVE SLAVE
Ruthie BenDor / @unruthless
Master-Slave. That’s definitely not going to evoke anything other than what was intended. Completely
neutral terminology.

31. WHITELIST
BLACKLIST
Ruthie BenDor / @unruthless
If you haven’t had enough inadvertent racism for the day, here’s another! Think about what a blacklist
connotes, and then tell me that this is neutral.

32. ALLOWLIST
BLOCKLIST
Ruthie BenDor / @unruthless
A cool thing I learned is that a number of organizations have actually started replacing its use of each of
these terms with ‘allowlist’ and ‘blocklist’, which is more precise and less accidentally racist.

33. http://imgur.com/a/GHHbI
Ruthie BenDor / @unruthless
ಠ_ಠಠ_ಠ
And then there’s this, that I think speaks for itself. // I’m going to broadly stereotype for a moment, to
say that people who write software and who write about software care about precision. We’re big into
‘technically correct’. The problem with things that are technically correct is that sometimes they are not
the most emotionally intelligent choice.

34. BECAUSE NAMING IS GUESSWORK,
AND WE OFTEN GUESS WRONG.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
Okay, another reason why naming software is hard. The first time we make something, or the first time
we write about making something, we’re making our best guess at what the appropriate name for the
thing is. And sometimes we guess wrong. When you’re naming a thing, you’re trying to distill it to its
essence, and maybe you don’t understand its essence yet.

35. WHAT ABOUT THIS WHISTLING ROARING SOUND GOING
PAST WHAT I’M SUDDENLY GOING TO CALL MY HEAD?
PERHAPS I CAN CALL THAT… WIND!
IS THAT A GOOD NAME?
IT’LL DO… PERHAPS I
CAN FIND A BETTER NAME
FOR IT LATER, WHEN I’VE
FOUND OUT WHAT IT’S FOR.
IT MUST BE SOMETHING VERY IMPORTANT BECAUSE THERE
CERTAINLY SEEMS TO BE A HELL OF A LOT OF IT.
Douglas Adams
https://www.flickr.com/photos/brainbikerider/8827814682
Ruthie BenDor / @unruthless
In The Hitchhiker’s Guide To The Galaxy, a whale materializes several miles above the surface of an
alien planet, and since this is not a naturally tenable position for a whale, it had to come to terms with
its existence in very little time, and it did so by naming things. At the beginning of a project I feel a bit
like this whale.

36. TASK
PAPER
Ruthie BenDor / @unruthless
BUT WHAT ABOUT
RECURRING TASKS?
NOPE
Naming is guesswork. When I started this ToDo app, I thought that I would just need notions of ‘Task’
and ‘Paper’. But then I discovered that I need a notion of ‘RecurringTask’ that’s notion of ‘complete’ is
different from ‘Task’, and it turns out that I don’t need a notion of ‘Paper’ at all, and now there’s all this
cognitive cruft in my code, and all my docs are wrong.

37. “MAKE IT WORK,
MAKE IT RIGHT,
MAKE IT FAST.”
Kent Beck
Ruthie BenDor / @unruthless
The fact that naming is guesswork, by the way, is why you can never avoid incurring technical debt, and you can never
avoid the need for refactoring. We discover what our software is meant to do as we write it. And it’s not until it’s written that
we are able to judge whether we’ve written it right. There’s a reason why “making it right” is the second, not the first, part of
this philosophy that guide’s how the Unix operating system is developed.

38. BECAUSE NAMING MATTERS EVEN WHEN
(ESPECIALLY WHEN) WE THINK IT DOESN’T.
WHY IS IT HARD TO NAME SOFTWARE?
Ruthie BenDor / @unruthless
At this point a reasonable person might say, look, all of this naming stuff seems to take a lot of brain
effort and we haven’t written a single line of code of that ToDo app. Maybe it doesn’t matter what
names we use within our software. It’s not like end users will ever see that stuff anyway, right?

39. Ruthie BenDor / @unruthless
I flew here on Saturday morning, and I took this photo in the airport. At least they used a reasonable
variable name. How bad would this have been if they’d called their internal variable name:
‘JerryIsAJerk’, or ‘txt’, or ‘foo’?

40. 2.
WHY DO BAD
NAMES PERSIST?
Ruthie BenDor / @unruthless
So those are some reasons why it’s hard to name software and so it’s not surprising that sometimes we
get it wrong. But, like, we’re not carving stone tablets here — it’s software — we’ve all got Delete keys
— why do bad names persist?

41. BECAUSE WE DON’T REALIZE
THAT THE NAME IS BAD.
WHY DO BAD NAMES PERSIST?
Ruthie BenDor / @unruthless
Maybe we don’t realize the name is bad. What does this most often look like?

42. THE PROBLEMS CAUSED BY THIS NAME
DON’T AFFECT ME, THEREFORE THEY
DON’T EXIST.
Colleague who is better with hardware than humans
EMPATHY FAILURE LOOKS LIKE:
Ruthie BenDor / @unruthless
It can look like an empathy failure. “The problems caused by this name don’t affect me, therefore they
don’t exist.”

43. THIS IS PERFECTLY CLEAR TO ME.
I DON’T UNDERSTAND HOW SOMEONE
CAN NOT UNDERSTAND THIS.
Colleague who’s been at the company forever
BEGINNER’S MIND FAILURE LOOKS LIKE:
Ruthie BenDor / @unruthless
It can look like a beginner’s mind failure. “This is perfectly clear to me, the person who wrote this thing
in the first place. I don’t remember what it was like to not understand this.”

44. WHAT DO YOU MEAN, ‘BING’ MEANS
‘SICK’ IN CHINESE?
Surprised and unhappy Microsoft executive circa 2009
LOCALIZATION FAILURE LOOKS LIKE:
Ruthie BenDor / @unruthless
Or, it can look like a localization failure.

45. BECAUSE WE RECOGNIZE THE NAME IS BAD,
BUT CAN’T OR WON’T JUSTIFY FIXING IT.
WHY DO BAD NAMES PERSIST?
Ruthie BenDor / @unruthless
Or, maybe we recognize that the name is bad, but we can’t or won’t justify fixing it. This is probably
familiar territory for all documentarians, because often your job is to explain something that, had it been
named better, wouldn’t have required an explanation at all. // So what can this look like?

46. BUT THIS NAME IS MY BABY!
Founder
SENTIMENTAL / POSSESSIVE FAILURE LOOKS LIKE:
Ruthie BenDor / @unruthless
It can look like a failure of over-attachment, maybe for sentimental reasons, to a name that is no longer
fit for purpose. This is a failure mode experienced by company founders a lot.

47. WHO MOVED MY CHEESE?
Every human ever
HUMANS HATE CHANGE FAILURE:
Ruthie BenDor / @unruthless
It can look like a simple knee-jerk hatred of change.

48. IF WE RENAME THIS, EVERYTHING WILL
BE BROKEN AND ON FIRE FOREVER.
Nervous engineer
OVERESTIMATE COST OF CHANGE FAILURE:
Ruthie BenDor / @unruthless
It can take the form of us overestimating the cost of changing a name, because charitably we’re
nervous, or don’t trust our own ability to estimate how long the renaming will take, or we’ve been
burned before on bad estimates, or, uncharitably we’re trying to weasel out of doing work.

49. I DON’T BELIEVE THAT CHANGING THIS
NAME WILL MOVE THE NEEDLE ON
WHAT WE CARE ABOUT.
Stakeholders
UNDERESTIMATE VALUE OF CHANGE FAILURE:
Ruthie BenDor / @unruthless
It can also take the form of underestimating the value that the improved name will generate. This is
projection, which means that on some level it’s guesswork. // So that’s why we live with bad names. We
either don’t recognize that it’s bad, or recognize that it’s bad but lack the will or ability or agency to
change it.

50. 3.
WHAT MAKES A NAME
GOOD OR BAD?
Ruthie BenDor / @unruthless
What makes a name good or bad? We think about this both when we’re writing software, and we also
think about this when we’re documenting software. And I struggle with how to answer this, because
naming is a balancing act.

51. http://publicworkshop.us/blog/2010/04/19/things-we-like-the-many-attempts-to-redesign-the-see-saw-err-teeter-totter/
Ruthie BenDor / @unruthless
A name shouldn’t be too long, but it shouldn’t be too short. It should adhere to your style guide, except
for when doing so would cause confusion. It should avoid ambiguity, unless the ambiguity is the point.
It should be easy to pronounce, unless that doesn’t matter for your use case. It should be memorable,
but not for the wrong reasons.

52. http://freethoughtblogs.com/pharyngula/files/2016/05/Context.jpg
Naming is a judgment call, and we can’t abstract or automate it away. The best I can do is share some
heuristics for assessing whether a name is good or bad in the context of being understood by the
humans working with it. Because good or bad is only meaningful in the context of the humans using
what we make, and learning from what we write.

53. CONFUSE, FRUSTRATE, MISGUIDE,
OBSCURE, OFFEND.
BAD NAMES
Ruthie BenDor / @unruthless
BAD names confuse, frustrate, misguide, obscure, or offend.

54. CONTEXTUALIZE, EXPLAIN,
ILLUMINATE, EMPOWER.
GOOD NAMES
Good names make a-ha moments happen, often by connecting or analogizing a virtual interface or
concept with a tangible one, in a way that correctly sets expectations about what the thing does, what
it’s responsible for, and how it might respond to a user’s interaction with it. // Good names
contextualize. They explain. They illuminate. They empower. They don’t break my brain’s shoebox filing
system.

55. Ruthie BenDor / @unruthless
https://commons.wikimedia.org/wiki/File:Lorimerlite_framework.JPG
It would undeniably be useful to have a rigorous mental framework for assessing a name’s quality. I’d
really like to have one, because that would mean that I would be able to think less about variable
names and think more about what’s for dinner. // But I think ultimately it’s a fool’s errand. No two
people’s frameworks are ever going to exactly match. Hell, my framework, the heuristics that I apply to
evaluate a name will change from day to day, as I learn and grow.

56. 4.
HOW CAN WE NAME
SOFTWARE BETTER?
Ruthie BenDor / @unruthless
Four. How can we name software better? I can tell you that it would be great if technology could solve
this problem for us. But there’s a reason that there is no FixMyBrokenNames App — I looked.

57. http://imgur.com/xETXroG
Technology can help us with the mechanics of naming well. For example, we can do a search for
similarly named things. We have automated linters and automated style guide enforcers that can, say,
prevent a variable from being too long or being capitalized inconsistently. And the tools we use to
document software are pretty good at exposing, say, inconsistencies in API method names.

58. http://www.someeecards.com
Ruthie BenDor / @unruthless
And all of that is valuable, to be sure. But it doesn’t help us much with the hard part of naming, the part
that requires our judgment. That’s on us.

59. https://xkcd.com/386/
Ruthie BenDor / @unruthless
We who write software and we who write about software and we who use software have a superpower:
our judgment about names is finely honed. We're pretty excellent at recognizing when names in
software leave room for improvement.

60. Ruthie BenDor / @unruthless
So here’s that To Do List: // Documentarians: let developers know when their names miss the mark. //
Developers: Writing software is an exercise in naming things. Embrace it.

61. http://dailydownwarddog.com/
Ruthie BenDor / @unruthless
Everyone: When you encounter a name that doesn't sit right with you, take a deep breath, and
remember that that poorly-named API method and nonsensical function signature is not here to spite
you.

62. Ruthie BenDor / @unruthless
https://www.schoolofsurvival.com/wp-content/uploads/2015/09/forge.jpg
Remember that software is made not by jerks on the Internet, but by humans like you and me, doing
the hard work of giving form and name to shiny new things that enable us to build the stuff of our
dreams.

63. Ruthie BenDor / @unruthless
RUTHIE@unruthless
Goodbye
I’m on the social network of your choice as @unruthless, and you should definitely @-mention me with
any other names you’d like to deconstruct. Thank you.