Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Even Naming This Talk Is Hard


Published on

A meditation on the difficulty of naming of and within software. Presented at Write The Docs Portland on May 15, 2017.

  • Be the first to comment

  • Be the first to like this

Even Naming This Talk Is Hard

  1. 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. 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. 3. “THERE ARE ONLY TWO HARD PROBLEMS IN COMPUTER SCIENCE: CACHE INVALIDATION AND NAMING THINGS.” Phil Karlton 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. 4. “THERE ARE ONLY TWO HARD PROBLEMS IN COMPUTER SCIENCE: CACHE INVALIDATION, NAMING THINGS, AND OFF-BY-ONE ERRORS.” Leon Bambrick 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. 5. 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. 6. http:// 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. 7. 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. 8. “EVERY TIME I LEARN SOMETHING NEW, IT PUSHES SOME OLD STUFF OUT OF MY BRAIN.” Homer Simpson 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. 9. Ruthie BenDor / @unruthless 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. 10. 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. 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. 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. 13. 1. WHY IS IT HARD TO NAME SOFTWARE? Ruthie BenDor / @unruthless First. Why is it so hard to name software?
  14. 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. 15. 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. 16. ? 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. 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. 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. 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. 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. 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. 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. 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. 24. CONTAINERCEPTION 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. 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. 26. InternalFrameInternalFrameTitlePaneInternalFr ameTitlePaneMaximizeButtonWindowNotFocuse dState 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. 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. 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. 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. 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. 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. 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. 33. 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. 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. 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 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 51. 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. 52. 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. 53. CONFUSE, FRUSTRATE, MISGUIDE, OBSCURE, OFFEND. BAD NAMES Ruthie BenDor / @unruthless BAD names confuse, frustrate, misguide, obscure, or offend.
  54. 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. 55. Ruthie BenDor / @unruthless 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. 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. 57. 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. 58. 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. 59. 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. 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. 61. 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. 62. Ruthie BenDor / @unruthless 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. 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.