 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 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. If you didn't catch your talk, please put it at the top of your list of two rewatch once the videos on demand go up. It was a wonderful talk. 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. And the problem that I want to talk about is names. Names of variables, 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 sign posts to fellow developers. Both current developers, people who are current coworkers, 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 variable names other than to avoid being killed by yourself and causing some sort of conflict, 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, 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 DjangoCon three or four years ago when I gave a talk on cash invalidation and caching within Django with my Cobra's inner no-assilus. So here's that quote. There are only two hard things in computer science, cash invalidation and naming things. Now, there are other sort of jokie versions of this, but this is the one that matters. And it's funny in its own right, right? Because you have this super, super technical thing, cash 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 still are the highest in difficulty, at least according to this quote. 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 or two times. So let's go over what I'm going to be talking about. This is a novice level course, so 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 restressing 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 it's 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. Maybe you went to Lacey's talk, maybe you've read the Pepe talks. That said, I'll cover Pepe 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 Pepe, I want to actually quote verbatim from Lacey's talk, she's talking about the elements of style, the English style guide by Strunk and White. The broader point about Strunk and White, though, is that this is a guide written to help people write clear, more concise, more consistent, more readable English. Pepe 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. The point of our names are these sign posts, and we want them to be clear, more concise, more consistent, and more readable. So I'm going to, like I said, really breeze through Pepe and what it has to say about naming variables. Even if you haven't read Pepe, 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 less decade. We all upper camel case our class names. We lower case and underscore our variable names and our method names and our function names. And we shout at the top of our lines 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. 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 read Pepe to learn more about that. And if you're sort of hugged by double underscores and I know it's a magic method that's used somewhere else in the life of the class. This is our guest host, Mark Twain. So I picked Mark Twain for a reason. Let me just move the mic. 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, go against the juxtapose, the British nature background of Jane Austen. He is a known for his simple, elegant, straightforward style. So I think we can all appreciate as Pythonistas, he has a really mean face. 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 it looks like a guy, if you're doing a code review with him, you don't want to take him off. Like this is a 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. And 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 above that. But I kind of want to try to fix this. There are more if you Google Jane Austen, Mark Twain, he's 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 to Jane Austen arm in arm and have them guide us to a nirvana of Python naming and 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. It is easy, right? Like we can directly use this as advice in naming our variables. Yesterday 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. 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 be using adjectives. And we read this and like, well, this doesn't translate to programming, right? We don't use really adjectives. Maybe properties, maybe arguments. 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. 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. Does it mean you need to fix it? Does it 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 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 the thousand and thousand in English words, that means the same thing. Now this is harder because it's a problem vocabulary. Sometimes you can't just Google that there's a new word and even if there is a different word, 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's another word. You can just call it ballot. I think this is probably of all the examples I have. I think this is a thing that the most people don't do because it's hard. You don't even have to think that much. You have to put in the effort to Google, 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 Toyn 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 Toynian way of saying context matters. Don't apply the rule universally. Don't be combative. You have to balance things out. You have to balance concises 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 context with us is do not omit necessary details. This comes up, I'll kind of give the silly example, when you use really vague words because maybe you're not sure at the time what the arguments are actually gonna be. So you just use vowel and you forget it. I mean, most of us know not to use something like this, but maybe there's a method like this that you've written before. And in this case, 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 it's kind of weird. It's parts of URL, URL prams. There's no kind of nice concrete word so why bother, I'll just call it D. And 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 D, too. And you can see how this just starts to compound and this, 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 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 need all this that don't get cute variable, right? They're a variable rule. It's saying variable all day long. So it can be really tempting to make a play on words or a pun or a cultural reference with our variable names. This is really common, maybe not super common, but most common in application names, right? You have your project and maybe that's acutely 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 an Egyptian 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 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 need to get cute beyond that. So there's one last advice that Mark has for us and it kind of encompasses everything, which is use of the right word, not its second cousin. This kind of comes up everything. Use the correct word, 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 comes up with consistency. Maybe, again, you think, oh, I wouldn't do this. 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 like, well, you're like, I don't want to change the other code and it might break things. So I'm just gonna start using the correct one. And then someone down the line says, well, now we're using URIs and URLs. So let's just start using address. But again, I'm too lazy. I don't want to fix the old code. And we'll just keep it going on now. 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 when we see what someone else used before and that's what I'm gonna keep on using. So I've also been talking about application code in this talk. And, should we do that again? Sorry. Okay. And it's important that test and documentations are different. We should treat them a little differently. And I think for both cases, verbosity is less of a sin. This is actually, I think, a completely fine test name. It's super verbose. You would never have a method in an actual class or a view named this. But I'm quite all right with it as 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 a break the rules in our test names, it's really easy to just use R and S and just short, short little names because who's ever gonna 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. So about foo and bar and baz, stop using it. Stop it, stop it, stop it, stop it. I own fozero.net. So I love the sort of lineage and the connection that makes me with programmers but stop using it. Especially, especially stop using in documentation. There are so many bad examples in documentation where it's written by a developer who knows the code so well and they know something is frivolous and they just wanna show some implementation detail and it doesn't matter what the context is. And there's also class foo, define bar and it munges a strain or something. Stop doing it. Someone will come along who doesn't isn't as experienced as you, doesn't know why you would wanna do this. And once a really good concrete example, the Djingodux are incredible at this. They have common motifs, the track title artist thing that are common throughout the documentation is concrete, it's universal, it's something that's really well-known. So the only other things I kinda wanted to add is that this has been very sort of general advice. The Martin quotes I think are awesome. They help you categorize a lot of other nitty gritty advice on how to write good variable names. Chapter two of Kling Code by 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 kinda summarizes that chapter to kinda get you started, but you should support the man by the book. And that's all I have. Are there any questions? So we have five minutes for questions. Okay, so I just, one comment and one question. My comment is in regard to the example used of ballot versus vote collection. And that's simply that, I mean, 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 card stock with the bubbles that you have to fill in with the black ink pen. With the, you know, with the candidate names on it. So it's like there's an actual, I think there's 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 transition doesn't occur very often. The other thing, the actual question was, there are times, I mean, because you know with the ORM, you can chain, you know, method calls to the end of the screen and beyond. And so oftentimes, you know, you wanna, you know, break that out and you can do that to a certain extent with, you 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 and add clarity in the separation of what's being done, but it's not necessarily carried over in the variable names. I mean, so I'd like to hear your feedback on that. Sure. On the comment first, I would defend even though a ballot may not be representing an actual physical ballot, and maybe there's another word for it, but as long as that is, 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 wanna say, again, don't get cute, but it's okay to be a little metaphorical when it comes to naming those things because if you're gonna be using ballot everywhere, you can kind of introduce, this is what a ballot is. For us, it is a collection of votes and you can kind of set that stone and hopefully your documentation can say that's what a ballot is. Sure. And just to get it on the microphone for the video, he was saying that there is such a thing as a ballot is a physical thing and it means something. I would say it depends, again, it depends, it's contextual, if you don't ever care about that physical thing, you know you're never actually gonna be talking about ballots, it's fine on that. On the question itself, I would say do your best when you do those throwaway variables, still name them contextually. You may end up using that variable in 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 like, well what was this before I did select related or prefetch related and then you know what, you can actually help it out. Prepare for edits and prepare for debugging later. Thanks for a great talk. It goes to the sort of ballot example as well for like we work in a community with a lot of non-native speakers as well. What are your thoughts around that sort of thing, clarity for non-native speakers that maybe don't have that level of vocabulary? Sure, this is, I'm gonna say, a hard problem and it depends entirely on your audience. I think open source, it's especially hard and I think you do end up just using those compound names that are hopefully avoided but that said, you know, I also don't think it's necessarily in the world if you say you're like, we're gonna use ballot even though it's not a physical ballot, we're gonna use ballot and I would say if you document it well, both within the code and within your documentation, that 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 kinda 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 coast and not use a word like that. I wonder if you might have words of wisdom on commit messages. So this is gonna be completely due, as I say, not as I do. I am until literally two months ago, I was probably the worst commit writer because I largely worked on projects by myself and I was like, who cares? So when I talk about future me, that is literally in the back of my mind. I'm looking through year old code and it says fixing bug, fixing bug, fixing bug, and I'm like, I'm an idiot. There's a really good blog post that came out a month or so ago and I really like that. Keep your subjects super short. I think the get recommendation is 50 characters. I go a little over that and then space, space and then a huge, as huge of a body as you need. And again, it's context dependent. If you're just fixing a bug, maybe the subject's fine. But if it's a merge, a feature branch merge, write as much as you can. Like even if you're copying, pasting docs or you copy and paste your commit message in the docs, it's not, more information commit messages isn't a bad thing. I'm sorry to have a comment, but it's not my comment. Okay. It's get absolute URL is poorly defined and poorly named. It is too late to fix it for JNK 1.0, but we should rethink it for JNK 1.1. I knew, I must say it's Jacob here. Yeah, I'll let the other, or the real Jacob, I guess. Comment on that whenever he wants. Okay, that's all the time we have. So stick around for the Microsoft winners being announced.