The Other Hard Problem: Lessons and Advice on Naming Things by Jacob Burch

Speaker 1: Lacey Williams gave a talk yesterday on the intersection between humanities and technology, specifically how her lessons as an English major influenced and helped her life in the tech world. I'm an English major as well, and as soon as I saw her abstract, I knew there was going to be a pretty big intersection between our talks. So we talked and uh plotted things out, and the core lesson that I kind of want to take from her is that There are soft problems, soft, in technology that we can use lessons from writers, lessons from your English professor, lessons from your high school English teacher to make us better programmers.

Speaker 1: If you didn't catch your talk, please put it at the top of your list of two re-watch once the videos on demand go up. It was a wonderful talk. I think a lot of people I think people both from humanities majors and people who from sort of more technical backgrounds have a lot to learn from it. But again, the core lesson I want to take away is that there are hard problems in computer science that are maybe not solved, but aided by some lessons we can take from humanities Uh and the problem that I want to talk about is names. Uh names of variables, uh names of methods, names of projects. Like the stylistic guides that Lacey covered yesterday, names are important because they're what we leave behind as signposts to

Speaker 1: fellow developers. Um both current developers, people work your current coworkers, uh people who may work with you later, and you, one year from now. You will want yourself, your old self, to have named things correctly. If you do not, future you will be mad at you. And that is how time travel movies start. And you do not want to be the protagonist in that movie. I promise you. Now there are other reasons why you want to have good burial names other than to avoid being killed by yourself and causing some sort of conflict. Uh but we'll go into those kind of when we get into the actual advice later in the talk. Speaking of names, my name is Jacob Birch. The name of the company I work for is RevSys. The name of my title is developer, I guess.

Speaker 1: And the name of this talk is the other hard problem. A lot of you probably know what the name of the talk is referring to. There's a quote that gets battled around. I used it in a talk here at Django Khan. uh three or four years ago um when I gave a talk on cache invalidation and caching within Django with my cobrazenter Noah Silas. So here's that quote. There are only two hard things in computer science, cache invalidation and naming things. Now there are other sort of jokey versions of this, but this is the one that matters. And it's funny on in its own right, right? Because you have this super super technical thing, cache invalidation, hard. CS grads have a really hard time with it And you have this super soft problem in naming variables. And that's why it's kind of funny that the two polar opposites of our discipline uh

Speaker 1: um still are the highest in uh difficulty, at least, at least according to this quote. And I'm grateful for that because that means my American literature degree was not gone to waste. I can use it in my professional life, even if it's just to give this talk one one or two times. So let's go over what I'm going to be talking about. Um this is a novice level course, so uh a lot of things I'll be saying may seem self-evident. to some seasoned developers here, but I kind of want to stress, and I'll be s re-stressing this throughout, that a lot of the mistakes here are not mistakes of ignorance, they're mistakes of laziness. It's easy to do the easy thing and just move on with your life even if you know the better. That said, I do think this is sort of a step two talk in that it's not I expect you to have a little bit of background on Pepe.

Speaker 1: Maybe you went to Lacey's talk, maybe you've read the Pepe talks. That said, I'll cover PEPAid a little bit. We have a special guest instructor that I'll introduce in a little bit who's going to give us some tips on naming our variables. And then I have a few notes just on how we can take these lessons and apply them to our tests and documentation. So to start up summing up Pep Bait, I want to actually quote verbatim from Lacey's talk. She's talking about the Elements of Style, the English style guide by Strunken White. The broader point of about Strunken White, though, is that this is a guide written to help people write clear, more concise, more consistent, more readable English PEP 8 is a guide for helping people write clear, more concise, more consistent, and more readable code. And that bears repeating, because it works exactly the same for names.

Speaker 1: The point of our names are these signposts. And we want them to be clearer, more concise, more consistent, and more readable. So I'm going to, like I said, really breeze through PEP8 and what it has to say about naming variables. Even if you haven't read Pep8, I think a lot of these are apparent if you just read a little bit of Python code that's been written in the last few years or last decade. We all upper camel case our class names, we lowercase and underscore our variable names and our method names and our function names, and we shout at the top of our lungs our constant names. There's a few slightly lesser known advice as well. We add a one underscore when we want to kind of suggest that this is a private method that may or may not get maintained.

Speaker 1: We can add a double underscore to really enforce the idea that it's a private method and Python will invoke some name mangling. Again, I'd read Pepe to learn more about that. And if you're sort of hugged by uh double underscores and denotes a magic method that's used somewhere else in the life of the class. So this is our guest, this is our guest host, uh Mark Twain. So I picked Mark Twain for a reason. Um I just moved the mic. Um so Lacey had Jane Austen helping us guide us through tests and through Pepe and through the importance of style guide. And I picked Mark Twain for a number of reasons. First is he's an American master to kind of compose the uh go against the uh juxtapose the British nature

Speaker 1: background of Jane Austen. He is a known for his simple, elegant, straightforward style, style I think we can all appreciate as Pythonistas. He has a really mean face. I don't know I I do not know if there's a picture of him smiling. There's pictures of him as a baby. He is not smiling. And he looks like a guy if he's you know doing a code review with him. You don't want to tick him off. Like this is the guy, he will have vengeance on you if you have a bad variable name. But the main reason I picked Mark Twain is he hated Jane Austen. I'm not kidding about this. I'm not going to say any of the mean things that he said about Jane Austen, because I would just be mean and cruel, and I'm I'm I'm above that. But he I kinda wanna I kinda wanna try to fix this.

Speaker 1: There are more if you Google Jane Austen Mark Twain. He's yeah, not a fan. But I want to fix this. I want in real Jane Austen style, I want to marry off mean old Mark Twain uh to Jane Austen arm in arm and have them guide us to the to a nirvana of Python naming and help have them both help us in both aspects of it. So the first bit of advice that Mark Twain has for us is use plain, simple language in short words. This is easy, right? Like we can directly use this in as advice in naming our variables. Yesterday uh at the there was a comment at the end of Lacey's talk, because I was trying to think of an example to show like what not to do, what violates this.

Speaker 1: And there was a comment about not using doc strings as your method name, which is brilliant. That's exactly how I want to put it. So this is a good example of that. So this is a hyperbolic example. You see this and you think, oh, I would never do that. That's not me. I know better. I use nice, concise, descriptive language. And that's true, like this is a very silly example. But I think there's another bit of advice where maybe we do fall into that trap and we don't even notice it. So this is one of the more well-known Mark Twain writing devices, which is when you catch an adjective, kill it. Nouns, verbs, these are the building blocks, and very, very sparsely should you be using adjectives. And we read this and we're like, well, this doesn't translate to programming, right? We don't use really adjectives, maybe properties, maybe arguments.

Speaker 1: But for the most part, nouns and verbs is kind of what we stick to. But I disagree. So look at this model name. And that's noun noun noun in this case, but we're using user and vote as adjectives. And it would be so much better if we just had one word to convey this. And there's a couple of techniques I want you to use when it comes to fixing this. The first, I guess three, because the first is when you notice that you're doing this, you're just shoving words together to create a new class. I just want a bell to go off in your head. Doesn't mean you need to fix it, doesn't mean there's something wrong, it doesn't mean it's a bad variable name, but it means there's an opportunity here to be better and to be more concise. The first technique we can use to actually fix it is

Speaker 1: what if we just got rid of one of the words? Do we lose any actual meaning? I find this happens a lot within models and especially with the user model. So many things are related to the user, so we add user to it, but there's no such thing in this case as a non-user vote collection So if we just get rid of the user, we have just as valid, just as descriptive, but a little bit shorter. And it matters when you start adding manager to things and view to things. Really helps the code stay concise There's another technique that's not quite as easy as just chopping something off. And that's if you can combine two or more words to mean to one single word, different word, somewhere in the dictionary of all of the thousands and thousands of English words, that means the same thing. Now this is harder because it's a problem

Speaker 1: vocabulary. Sometimes you can't just Google that there's a new word, and even if there is a different word, it doesn't mean you should use it. If it's a word that's not kind of widely understood by the people you're coding with, you still shouldn't use it. Luckily for us, vote collection in this mythical model that we're using, there is another word. We can just call it ballot. I think this is probably of all the examples I have, I think this is the thing that the most people don't do. Because it it's hard. You have to think you have to put you don't even have to think that much. You have to put in the effort to Google like m is there a domain word that I'm not thinking of that I could be using. So I want to go back to that last bit of advice that

Speaker 1: Twain had for us because this is actually not the complete quote. When it gets quoted, this is usually all you see, but it's not the complete one. This is the complete one. When you catch an adjective kill it, no, I don't mean that utterly, but kill most of them. The rest of them will be valuable. And this is sort of a twinian way of saying context matters. Not all don't apply the rule universally, don't be combative. You have to balance things out. You have to balance concisess with descriptiveness. And I want to make it clear that every little bit of advice I give you, again, bell goes off in your head. It's not universal. Another bit of advice that we definitely have to take contacts with us is do not omit necessary details This comes up, um, I'll kind of give the silly example when you use really vague words

Speaker 1: because you're maybe you're not sure at the time what the method is actually what the arguments are actually going to be. So you just use vowel and you forget it. I mean most of us are know not to use something like this, but maybe there's a method like this that you've written before. And in this case, you know, maybe there's one line after this where you return the response of a request. So why bother? Why bother calling it trying to figure out what D actually is? Because I mean it's kind of weird. It's parts of URL, URL params. There's no kind of like nice concrete word, so why bother? I'll just call it D. And that's that's fine until you notice that maybe this method needs to get worked on by someone else. And in that case, d is only the second worst variable name that will be contained in this function. Because the worst variable name is D2.

Speaker 1: And you can see how this just starts to compound, and this I I can almost guarantee every one of us has done this. maybe not recently, but we've done this. And it's really tempting to do. It's really tempting to do in test code. And I'll get to that in a little bit. Because it's the second example of something. I don't have I don't want to think about how it's changed or how it's different. So I'll just move on. So what does Mark Twin have for us next? Don't let fluff and flowers and verbosity creep in. So we can call this the don't get cute variable, right? Or variable rule. Um same variable all day long. Uh so it's t it can be really tempting to make a play on words or a pun

Speaker 1: or a cultural reference uh whether our variable names. This is really common, maybe not super common, but more com most common in application names. Right? You have your project and maybe that's cutely named. And that's fine. You kind of want your project name to be marketable, to be searchable, to be unique, says the guy at a conference named after a gypsy guitarist. But beyond that, keep it boring. Don't be cute. If you need to show your creative energy, show it when you name your project. Think of it, you have a beautiful baby boy and you name him Mark. And that's it. Maybe it's a it's a a family name. But you don't go out of the way to name his hair or his mustache. There's just his hair and his mustache. You don't don't you don't need to get cute beyond that

Speaker 1: So there's one last advice that Mark has for us, and it kind of encompasses everything, which is use the right word, not its second cousin. Uh this kind of comes up everything. Use the correct word. Does like as descript as it needs to be, as brief as it can be, use the right word. But I think this has another sort of anti-pattern that comes into play and that's comes up with consistency. Maybe again you think, oh, I wouldn't do this. I I have a name for URLs and that's the one I use. But maybe you're in a project where they were using URI when they really meant URL. And you're well, you're like, I don't want to change the other code, it might break things. So I'm just going to start using the correct one. And then someone down the line says, well, now we're using URIs and URLs. So let's just let's just start using address. But again, I'm too lazy. I don't want to fix the old code Uh and we'll just keep it going on now.

Speaker 1: Now you have code that's harder to parse, you have code that's harder to refactor because you have to search for all three of these, and it's just not as pleasant as just saying this is what we're using. Let me see what someone else used before, and that's what I'm gonna keep on using. So I've mostly been talking about uh application code uh in this talk. And Um show me that again, sorry. Um And it's important to uh that test tests and documentations are are different. Um we should treat them a little differently. And I think for both cases, uh verbosity is is less of a sin. Uh this is actually I think a completely fine test name.

Speaker 1: It's super verbose. You would never have a method in an actual class or a view named this. But I'm I'm quite alright with it. as uh a test name because you're never really invoking this everywhere else or I can't imagine a place where you are. So the only place you're using it it's sort of a chapter title when you're reading your test or someone else is reading your test. And if the test fails, it points to you exactly to what's failing. Now that said, because we kind of get to break the rules in our test names, it's really easy to just use uh R and S and just short short little names, because who's ever going to read this ha ha ha? But people will. People will need to change the test. Maybe they'll need to introduce another variable that starts with an R. So just be explicit when you can. It doesn't take that much more time and it's just worth it. to not use something like foo and bar and baz.

Speaker 1: So about foo and bar and baz. Stop using it. Um stop it. Stop it, stop it, stop it. Uh I own F00. net, so I love the sort of lineage and the connection that makes me with programmers, but stop using it. S especially, especially stop using in documentation. There are so many bad examples uh in documentation where It's written by a developer who knows the code so well and they know something is frivolous and they just want to show some implementation detail and it doesn't matter what the context is. And those class foo, define bar, and it munges a string or something. Stop doing it. Someone will come along who does isn't as experienced as you, doesn't know why you would want to do this, and wants a really good concrete example. The Jingle Docs are incredible at this.

Speaker 1: They have common motifs, the track title artist thing, that are common throughout the documentations. It's concrete, it's universal, it's something that's really well known. So the only other things I kind of wanted to add is that this has been very sort of general advice. Uh the Mart Tain quotes I think are awesome. They help you categorize a lot of other nitty-gritty uh advice on how to write good variable names. Uh chapter two of clean code by um Uncle Bob, Robert Cecil, Martin. is really really good at this, has a laundry list of rules that you can follow. I highly recommend buying the book and reading it. I'll also be linking to a source when I publish this talk on GitHub. that uh kind of summaz it summarizes that chapter to kind of get you started, but you should you know

Speaker 1: support the man by the book. And um that's all I have. Are there any questions?

Speaker 2: So we have uh five minutes for questions.

Speaker 3: Okay, so I just uh one comment and uh one question. Uh my comment is in regard to the example that you used of uh ballot versus vote collection, and that's simply that I mean I I love words, I love what they mean, I love the subtleties of them, but like in common North American parlance, when you say ballot, what people think of is they think of that piece of cardstock with the bubbles that you have to fill in with the black ink pen uh with the you know with uh candidate names on it. So it's like there's an actual, I think there's a a um a clarity in vote collection. That unfortunately is a lowest common denominator type target. So I mean, I like what you're saying. I completely agree with you, but then I also understand why that final

Speaker 3: transition doesn't occur very often. The other thing I want the my actual question was Uh there are times, you know, I mean, because you know with the with the ORM you can chain uh you know method calls. Uh you know, to the edge of the screen and beyond. Um and so oftentimes, you know, you want to you know break that out. And you can do that to a certain extent with um you know know, just indentions, you know, next line indentions. But sometimes you literally do have a variable, it's just a throwaway variable. It doesn't mean anything other than I want to assign this blob of stuff someplace such that I can then do additional work on it.

Speaker 3: And uh add clarity in the separation of what's being done, but that's not necessarily carried over in the variable names. I mean, so I'd like to hear your feedback.

Speaker 1: Sure. On the comment first, um I would defend even though a ballot may not be representing an actual physical ballot, uh and maybe there's another word uh for it, but As long as that is your like our models tend to be our sort of our starting blocks for nouns thereafter, views and managers are named after the model. I think it's okay, I don't want to say again, don't get cute, but it's okay to introdu be a little um metaphorical when it comes to naming those things. Because if you're going to be using ballot everywhere, you can kind of introduce this is what a ballot is. For us, it is a collection of votes. Um, and you can kind of set that stone and hopefully in your documentation you can say that's what a ballot is. Oh yeah, I mean But you know, that that's a legitimate definition to say that a ballot is, you know, like

Speaker 1: a run candidate. Sure. Um and just to get it on the microphone for the video, uh he was saying that there is such a thing as a ballot as a physical thing. and it means something. I would say it depends it again, it depends. It's contextual. If you're if you're you don't ever care about that physical thing, you know you're never actually going to be talking about ballots. It's fine on that. On the question itself, I would say do your best when you do do those throwaway variables, still name them contextually. You may end up using that variable and an edit later. It's also really important when you're debugging of test breaks and you throw in a PDB, you know what you're you're like, well what was this before I did select related or prefetch related. And then you know what you can actually help it out. Um prepare for edits and prepare for debugging later.

Speaker 1: So

Speaker 4: Thanks for a great talk. Thank you. What are your thoughts around that sort of thing, uh clarity for non-native speakers that maybe don't have that level of vocabulary.

Speaker 1: Sure. Uh this is I'm gonna say say a hard problem. Uh and it d it depends entirely on your audience. I think opa open source it's especially hard and I think you do end up Just cut using those compound names that are hopefully avoided. But that said, you know, i i I also don't think it's necessarily in the world that if you j if you say you're like We're gonna use ballot, even though it's not a physical ballot, we're gonna use ballot. Uh and I would say if you document it well, both within the code and within your documentation, that this this is a metaphorical term we're using so we can keep things concise and concrete and easy to parse. A big problem with user vote collection is you kind of have to read all three words before you know what you're talking about, versus once you see ballot you can kind of contextualize it like that. But again it's hard. Sometimes you just have to give up the ghost and not use a word like that.

Speaker 5: I wonder if you might have words of wisdom on commit messages.

Speaker 1: So this is gonna be completely do as I say, not as I do. I am until I liter literally two months ago, I was probably the worst um commit writer because I largely worked on projects by myself and I was like, ha ha ha Who cares? So when I talk about future me, that's the that is literally in the back of my mind going, I'm looking through year old code and it says fixing bug, fixing bug, fixing bug, fixing bug, and I'm like, I uh uh an idiot. Um There 's a really good blog post that came out uh a month or so ago and um I really like that. Keep your subjects super short. I think the get recommendation is 50k. characters. I go a little over that. Um and then space, space, and then a huge as huge of a body as you need. And again, it it's context dependent.

Speaker 1: If you're just fixing a bug, maybe the subject's fine. But if it's a you know a merge, a feature branch merge, write as much as you can. Like even if you're copy and pasting docs or you're cop you copy and paste your commit message in the docs. It's not more information can commit messages isn't a bad thing.

Speaker 6: I'm sorry I have a comment, but it's not my comment.

Speaker 1: Okay.

Speaker 6: It's get absolute URL is poorly defined and poorly named. It is too late to fix it for Django 1. 0 But we should rethink it for Jenka one point one.

Speaker 1: I knew I was about to say is Jacob here? Yeah, I'll let the other Jacob or the real Jacob, I guess, uh comment on that whenever he wants.

Speaker 2: Okay, that's uh all the time we have, so stick around for the Microsoft winners being announced.