Even Naming This Talk Is Hard

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-
suﬀering friends will attest, so this is gonna be fun. // Before we get to names in software, let’s start
with my name.

RUTHIE
@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.

“THERE ARE ONLY TWO
HARD PROBLEMS IN
COMPUTER SCIENCE:
CACHE INVALIDATION AND
NAMING THINGS.”
Phil Karlton
http://blog.modernmechanix.com/machine-solves-hard-problems
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 ﬁnd me at the bar later. // I’m starting with this truism
because it’s, well, true, but also because there’s an amended version.

“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
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.

https://www.prodataloggers.com http://matt.might.net/articles/phd-school-in-pictures/
circle containing all human knowledge
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 ﬁeld,
mainstream software development these days is largely an exercise in making things with other
people’s code.

http://http://gooddogsoftware.com/
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.

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

“EVERY TIME I LEARN
SOMETHING NEW, IT
PUSHES SOME OLD
STUFF OUT OF MY
BRAIN.”
Homer Simpson
https://www.planetclaire.tv
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 ﬁrst piece of information that we have about this new abstract construct that we’re
getting to know?

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 ﬁling system. So names are pretty important.

http://lifehacker.com/the-only-technique-to-learn-something-new-1709323497
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?

ಠ_ಠ
‘What even is this’, and ‘What do I do with this’, and ‘Am I dumb?’ and ’I have no idea where this goes.’

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?
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.

1.
WHY IS IT HARD TO
NAME SOFTWARE?
First. Why is it so hard to name software?

BECAUSE THE GOOD NAMES ARE
ALREADY TAKEN.
WHY IS IT HARD TO NAME SOFTWARE?
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 speciﬁc for a bit. // Let’s go through an exercise of creating and
documenting some software together.

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 oﬀ 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.

?
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.

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….

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.

Now, if I were a marketer or a brand strategist, this would meander oﬀ into a discussion of naming
products. And there’s deﬁnitely 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.

BECAUSE THE GOOD NAMES TERMS ARE
ALREADY TAKEN OVERLOADED.
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 speciﬁc meaning in computer science, to be fair, but it’s
really unnecessary here. Some real world examples.

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.

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.

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 deﬁnitely didn’t confuse me for about a month and a half.

CONTAINERCEPTION
http://imgur.com/Gp41aN6
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.

BECAUSE NAMING IS REDUCTION,
AND WE ARE BAD AT CHOOSING WHAT TO EXCLUDE.
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.

InternalFrameInternalFrameTitlePaneInternalFr
ameTitlePaneMaximizeButtonWindowNotFocuse
dState
http://www.pushing-pixels.org/2007/11/07/and-the-longest-jre-class-name-is.html
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.

BECAUSE NAMES EVOKE,
AND WE ARE BAD AT ANTICIPATING WHAT.
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 diﬀerent contexts. The following examples range from questionable to
appalling.

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.

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?

MASTER
SLAVE SLAVE SLAVE
Master-Slave. That’s deﬁnitely not going to evoke anything other than what was intended. Completely
neutral terminology.

WHITELIST
BLACKLIST
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.

ALLOWLIST
BLOCKLIST
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.

http://imgur.com/a/GHHbI
ಠ_ಠಠ_ಠ
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.

BECAUSE NAMING IS GUESSWORK,
AND WE OFTEN GUESS WRONG.
Okay, another reason why naming software is hard. The ﬁrst time we make something, or the ﬁrst 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.

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.ﬂickr.com/photos/brainbikerider/8827814682
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.

TASK
PAPER
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
diﬀerent 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.

“MAKE IT WORK,
MAKE IT RIGHT,
MAKE IT FAST.”
Kent Beck
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 ﬁrst, part of
this philosophy that guide’s how the Unix operating system is developed.

BECAUSE NAMING MATTERS EVEN WHEN
(ESPECIALLY WHEN) WE THINK IT DOESN’T.
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?

I ﬂew 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’?

2.
WHY DO BAD
NAMES PERSIST?
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?

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

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:
It can look like an empathy failure. “The problems caused by this name don’t aﬀect me, therefore they
don’t exist.”

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:
It can look like a beginner’s mind failure. “This is perfectly clear to me, the person who wrote this thing
in the ﬁrst place. I don’t remember what it was like to not understand this.”

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

BECAUSE WE RECOGNIZE THE NAME IS BAD,
BUT CAN’T OR WON’T JUSTIFY FIXING IT.
WHY DO BAD NAMES PERSIST?
Or, maybe we recognize that the name is bad, but we can’t or won’t justify ﬁxing 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?

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

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

IF WE RENAME THIS, EVERYTHING WILL
BE BROKEN AND ON FIRE FOREVER.
Nervous engineer
OVERESTIMATE COST OF CHANGE FAILURE:
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.

I DON’T BELIEVE THAT CHANGING THIS
NAME WILL MOVE THE NEEDLE ON
WHAT WE CARE ABOUT.
Stakeholders
UNDERESTIMATE VALUE OF CHANGE FAILURE:
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.

3.
WHAT MAKES A NAME
GOOD OR BAD?
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.

http://publicworkshop.us/blog/2010/04/19/things-we-like-the-many-attempts-to-redesign-the-see-saw-err-teeter-totter/
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.

http://freethoughtblogs.com/pharyngula/ﬁles/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.

CONFUSE, FRUSTRATE, MISGUIDE,
OBSCURE, OFFEND.
BAD NAMES
BAD names confuse, frustrate, misguide, obscure, or oﬀend.

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 ﬁling
system.

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.

4.
HOW CAN WE NAME
SOFTWARE BETTER?
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.

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.

http://www.someeecards.com
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.

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

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.

http://dailydownwarddog.com/
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.

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 stuﬀ of our
dreams.

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

Even Naming This Talk Is Hard

More Related Content

Similar to Even Naming This Talk Is Hard

More from Ruthie BenDor

Recently uploaded

Even Naming This Talk Is Hard