Jane Austen on PEP8... by Lacey Williams Henschel

Speaker 1: Hi y'all, thank you so much for for having me. Um I'm really excited to be here. So let's just get started. Um about me. I am Lacey. I'm a developer for the University of Texas where I've been for the past four years, and now I'm gonna try to slow down I'm not gonna talk that fast for the rest of the talk. It's gonna be great. Um But before I became a developer, I really wanted to be an English professor. I got my bachelor's degree from Auburn University in 2007. And while I was there, I did a lot of tech things. I was the webmaster for my professor's website, which was maintained in Dreamweaver and stored on a zip drive. Those were good days. Um, I also worked in the technology center where I screencasted videos to teach professors how to use Blackboard. Which is an online course management system if you've not if you're not familiar with it.

Speaker 1: And I also helped them integrate tech into their classrooms in ways that I thought were cool. Then, because I still wanted to become Professor Lacey and I wanted to teach and write scholarly articles about literature like articles about Jane Austen, I got a master's degree in English from Texas A<unk>M University That's just a couple of hours down the road in college station if you're not familiar with Texas geography. Again though, I steered myself into more tech roles. I worked in the technology center instead of being a teaching assistant, which is what you're supposed to do And I helped faculty screencast and make videos and use Moodle, which is an open source version of Blackboard. But I didn't know what open source was at the time. I just knew it was free. And then I also helped them integrate Google Docs as a collaboration tool in their classrooms. I also worked for an organization called the World Shakespeare Bibliography.

Speaker 1: which takes all of the articles that are written about Shakespeare and puts them all into one place. So it's pretty cool. While I was there, I wrote summaries on these articles, but I had to use some XML markups so that they could be copied and pasted into our administrative site. I didn't know that that was kind of like coding. Then in 2009, I took a workshop on TEI, the Text and Coding Initiative. TEI is an XML markup language that's specific to manuscripts. So, this is an example of what it looks like. On the left, you have what is being transcribed, and on the right, you have the TEI XML markup There's also some links at the end of the presentation, and I'll post these slides online. So if you're really interested in TEI, you can dive deep into that. It has these really awesome and specific tags for manuscripts. So there's a tag for the publisher

Speaker 1: the date, the author, the title. But then you can do really neat stuff for written manuscripts. So like there's a way to represent in markup that Mark Twain scratched through a line and then wrote something else above it, which is really neat. I wanted to make a site using TEI whenever I was in grad school to talk about Jane Austen fanfiction And that's actually a really rich world. There are these like Twitter accounts where people will will become the different characters from Pride and Prejudice, for example, and they will like over a period of time act out the entire novel and it's it's really fun. People get into this. So like you think that you know you're gaming or DragonCon or whatever, and you haven't met these Jane Austen

Speaker 1: people. That is real fandom. Um but I I didn't know how to make a website. I was really tech inclined and tech interested, but I didn't think of myself as tech savvy despite like everything I've told you about all the tech things that I was doing Um I didn't know how to register a URL. I didn't understand what CSS was, and if there were tutorials out there, I didn't know where they were. I wish that I could go back and mentor myself in 2010 And I was telling Barbara about this this morning because now there's the Django Girls tutorial and I could say, 2010, Lacey, you should do this because Django would be perfect for what you want to do. But I didn't know that. I had imposter syndrome before I even got started. So instead of doing my amazing website on Jane Austen fanfiction, I wrote a paper on Jane Austen fanfiction. And with that I got a digital humanities certificate.

Speaker 1: Which is still ironic to me that that even was allowed to happen. Um this talk, Jane Austen on Pep 8, is sort of my do-over. It's a chance for me to talk about literature and tech in one place, which I've never gotten to do before So this is for the other English majors, the bookworms, the lovers of literature, the people with humanities degrees who struggle with that question. So do you ever use your history degree? It's also for the people who have asked that question of their colleagues that don't have STEM backgrounds, who've been confused about how someone might start out a psychology major and wind up writing Python. The truth is that the technology world and the humanities world are not very far apart. A lot of the concepts that English majors have perfected over years of writing thesis papers, we do use in our daily lives as developers. This talk isn't really about what coders can learn from humanities majors or vice versa.

Speaker 1: It's more a demonstration of the overlap between those two disciplines and a study in their compatibility and how they complement one another. So, this is a game called Guess the Source. I put up a quote from a style guide, and you guess where it comes from. And this is the Jane Austen handwritten thought, which means it's a little bit difficult to read, but I just couldn't resist. So it says um always use two spaces after a sentence ending period. Any guesses? It's actually PEP eight. Woo, yeah. So that's kind of the first clue that writing code has anything to do with writing a research paper or an essay. Pep8 also says when writing English, follow strunken white. And Pep8 doesn't even cite strunken white. It never actually says the elements of style.

Speaker 1: It just assumes that you know what that means. So if you don't know what we mean when we say strunk in white, strunk in white refers to a book called The Elements of Style, which got shouted out out here. It's an American English style guide that was first published in 1959 Now I hate this particular line from PEP 8 because in your regular writing you should never do this. This is from the days of monospace fonts and typesetting, and we don't use monospace fonts on the internet or in our publishing anymore, except in code. So you should follow this rule when you're writing code, but you should break it everywhere else. My broader point about Strunken White, though, is that it's a guide written to help people write clearer, more concise, more consistent, and more readable English. PEP 8 is a guide for helping people write clearer, more concise, more consistent, and more readable code.

Speaker 1: So let's talk about plot-driven development. Let's talk about testing. Testing is a perfect example of where some concepts from your literature class can come in handy. So you might remember this from your like you know great books 101 or something, but this is Freytag 's pyramid, and this is just a basic illustration of a story arc. You have exposition, which is where you learn who the characters are, where you're at, and the basics of what's happening. You have the rising action, which is where the problem gets introduced, and we start experiencing the events that lead us to the climax. Now this the climax is the most exciting part of the plot. This is where the thing happens that changes the main character's fate. So in Pride and Prejudice, this is the scene where Mr. Darcy finally proposes to Elizabeth, but she says that she would not marry him if he were the last man on Earth.

Speaker 1: And then she starts to question herself. Um the following action is when things begin to unravel and fall into place, so we figure out that Mr. Darcy is actually a nice guy. He did her family this huge favor, and then we have the denouement where they get married and everything is tied up in a neat little bow. We can make use of this arc in testing as well. In fact, that was the idea that that was where I got the idea for this talk. I was at PyCon earlier this year, and I was in Harry Percival's testing tutorial, and I realized that the example of a functional test that he gave was an example of a plot. So this is a more formal version of my answer to a question I got after that tutorial when I was chatting with someone and told them I had an English degree, and they said, so do you ever use your English degree? So in Harry Percival's example of a functional test, he takes us through the plot or the pyramid of someone's journey through this sample-to-do

Speaker 1: list app. His example has exposition. He introduces us to Edith, who has heard about this fancy to-do list app. It has rising action. Edith locates the app, she goes in, she finds her way around, and she makes the decision that she's going to enter an item. Then there's the climax. Edith's fate is forever changed. She forms she performs the crucial pivotal action of adding an item to her to-do list. There's the following action. She's entered the item. She sees that it's been entered and saved. And then the denouement, Edith is happy and she goes back to sleep. Before Harry ever writes a single actual functional test, he writes out this whole story that follows that plot arc.

Speaker 1: This way, he knows what path the user needs to take through his site, what they'll encounter, what they'll do, and how it will all resolve. He can write tests to test that these steps happen, and then he writes the code to pass that test. We all know what testing is, so Um the path that Edith takes through the app though that's her plot and Edith is a character. In another world, Edith might be the protagonist in a novel, and this particular journey might be a chapter in what I hope is an otherwise more thrilling story. The ability to write a complete and convincing user story though is helped by having studied character development and plot development. A programmer needs to be confident in what their code is supposed to do and in what order that's supposed to happen in order to effectively test it. And user stories and functional tests are not the end of the story.

Speaker 1: How do we want Edith to react whenever the app breaks? Do we want her to tear her hair and rend her garments like she's in a Greek tragedy? I certainly hope not. We probably want to provide her with the tools that she needs to correct the error, if possible, or reassure her that we know that something went wrong and we're already on it. So then we have this more reassuring error message that I'll again I'll read for you because I just love this font, but it's not readable. Dear readable, or sorry, dear reader. We regret that an error has been made. Warmly, the programmers It takes some creative thinking to know where our code might break, to build in checks for that, and to return something useful to our user. Any programmer can return the error message, assertion error false is not true. But it takes some creative thinking, as well as those excellent written and verbal communication skills that you see in job postings but you never know quite what they mean.

Speaker 1: To compose an error message that is helpful, not intimidating, and is confidence inspiring. When you're writing good tests, you're doing world building. Accessibility, for example, requires empathy, and empathy requires imagination. You can leverage that awesome feeling you get when you get really lost in a book and you identify with the main character super closely. into putting yourself in the shoes of your user. Imagine their struggles, their frustrations. Create a persona for them and fix the things that hinder them or annoy them about their app, about your app, and let them continue on their journey. But back to the functional tests. So this is a screenshot from Harry's book, Test-Driven Development in Python. Specifically, it's all of the comments that he's written out so that he knows what tests he needs to add.

Speaker 1: This also looks like something else though that you may remember from your college English classes. An outline. It has specific ideas in a specific order. They relate to each other in a specific way. And that looks like something else. Basically all Python code. Python loves whiteface white space and indenting and pretty formatting even more than the average English major. Python uses a lot of the same formatting as many other written works, like news stories, blog posts, novels, research papers, even recipes like this one, which is Emily Dickinson's handwritten coconut cake recipe. Your function definition is like the title. And to convince you of that even further, you should really check out Jacob Birch's talk on naming things tomorrow. I'm not gonna spend a lot of time on naming things because that's what he's here for

Speaker 1: Your doc string you can think of as like the abstract to a research paper or the foreword to a new edition of a favorite novel. It tells you a little bit about what's coming, it gives you a peek into the author or the programmer's mind. Then there's everything in the middle. There's the meat of your function, the paragraphs of the article or the story. And finally, you conclude. You return something, and your journey through this particular function is over. A well-written piece of code will be readable, but what do we even mean by that? Machines don't need code to be readable, but then we have this. The Zen of Python is pretty clear that readability counts. The computer or compiler doesn't care if your code is a mess. But your colleagues care. The people who come after you care. The people who share in your work need your code to be readable

Speaker 1: It takes caring about your fellow coder to write readable code. Readable and conscientiously commented code also helps future programmers understand what you struggled with or why you made decisions the way that you did. A friend of mine once said, comments are like love notes to yourself. Another coworker likes to say that comments are what keep you sane at 3 o'clock in the morning when you get a phone call that something has gone catastrophically wrong. Now, there's a great example of this from a contemporary series that some of you might have read. It's the Outlander series. This is basically my perfect book series. It's about a World War II nurse who accidentally time travels back to 18th-century Scotland. It's amazing. Um there's war and there's romance and there's wonderfulness and it's a pretty great TV series too, but none of that is the point

Speaker 1: I'm not gonna spoil anything, but I will say that at the end of book five, this is like an eight-book series, um our heroine Claire is in 18th century, and she's the most knowledgeable medical professional for miles. She treats someone who winds up dying, and she's pretty sure it's because she gave the patient something that they were allergic to. And she struggles with whether to write this down in her medical journal where she keeps records of all of her patients Because in a different book, she was uh tried as a witch because they thought that her medical amazingness was actually witchcraft. So she doesn't want want to write something down that could be used against her. She says this, and I quote, some future physician here would face the same dilemma, to undertake a possibly dangerous treatment or to allow a patient to die who might have been saved. Who might that be? And then she thinks for a while about how isolated she is, about how there aren't very many doctors and there aren't really very many medical schools, and then she concludes.

Speaker 1: I sat up straight and opened my book. I dipped my pen and began to write the lines that must be there for the sake of the unknown physician who would follow me. Now, we're not saving lives here, but this is why we write readable code for the sake of that unknown coder who follows us. So when I was in college, I had a roommate who was a journalism major, and she and I would always edit each other's papers, and I would invariably try to get her to use more adjectives to make her writing more exciting. And she would tell me to cut my flowery descriptions and get to the point. She was right. These next few slides are edicts from PEP 20 and Strunken White. And I'm not going to specify which line is from which work because it doesn't matter. The point is that they're so similar. Good writing is concise and clear and simple and gets to its point, whether you're writing a piece of code or an article.

Speaker 1: I could take the lines from the Zen of Python that aren't specific to code and email them to my friends who are now English professors and they could just hand them out right now to their classes and they would be better for it. In fact, I should do that. So much of what makes the Zen of Python great is its universality. My favorite line is complex is better than complicated, not because I struggle with writing code that is complex and instead of complicated, but I do But it's because it speaks to the writer in me. It's really hard to explain a complicated idea or to come around to an important point at the end of a long thought journey. I got a little lost there. That's cool. I made it like a long time without doing that. It's why a good editor and a good code review are both so valuable to us as writers.

Speaker 1: And anyone who's a fan of Game of Thrones knows how thin the line between complex and complicated can be. So what would happen if we didn't call ourselves coders or programmers or developers? What do we do all day? We write code. We read comments. We write tests. We read pull requests. We write A lot of things. We're readers and we're writers. The lessons that we learned in classes about reading and writing literature are exceedingly relevant to us as readers and writers of code. So do you ever get to use your English degree? I get asked that all the time. And I use my English degree every day. And then I have some sources. So

Speaker 1: And I will take questions, so if you have questions, feel free.

Speaker 2: Thanks, it's great. Great talk. Are you familiar with literate programming?

Speaker 1: No.

Speaker 2: Okay, so literate programming was something that uh Donald Nuth, who's uh a big CS professor, came up with with the idea that uh the documentation for code and the code should be the same thing and that effectively you can you compile it to documentation you compile it to code. I was wondering your thoughts in terms of Do you think that it should actually be at that level of verbosity, that level of engagement between the code you're writing and what's being is there? Or is, in your opinion as someone who's coming from a humanities, the code literate enough to express what's going on.

Speaker 1: So I know um and I I knew that someone was gonna say like, well don't you think that, you know Code should be self-documenting and and it should, that's true, right? But that's not always what happens. And I know that we've all maintained those legacy systems where maybe once upon a time that code was self-documenting, that time is Passed. That time is over now. And we are now at a new era where we have no idea what this code does and no one wants to touch it because it works, but we have no idea why. Um ideally Ideally, our code would be self-documenting and there would be no need for, you know, hashes that had comments after them. Um I, however, think that especially whenever you're writing that really complex code that is responding to a a really difficult problem or a really difficult idea that took you a while, or whenever you're doing something new for the first time, it's nice to leave someone or yourself

Speaker 1: breadcrumbs that say like this is what I'm meant to do, this is what this code does. Um this is what I was thinking, this is how I got here. And um and I I I think that leaving those breadcrumbs is a kind thing to do. I'm pro comments And even being pro comments, I still get um comments in code review like, why don't you document that? Like UT is very pro, like you should add a comment. To tell us what you meant here. Especially since at a larger institution there are so many different kinds like different we're all little tiny silos of business rules, and so everyone has slightly different things that they have to think about Sure. Um but yes, I I do believe that good code is self-documenting. I I think that that's not always the code that we wind up writing.

Speaker 1: Right

Speaker 3: talk by the way, fellow English major. Yay! I see

Speaker 1: more of us.

Speaker 3: Now my only comment about your I mean The complexity versus what was it? Complexity versus complex.

Speaker 1: Complex versus complicated.

Speaker 3: Complex versus complicated. And that is one of the reasons why I didn't become a writer professionally was because, well, for one, I didn't do it every day Which is of course what they tell you you have to do, right? But I think at the English language though is it's it it's like there's a struggle. Uh we become really jargonized. And so it's really hard for people to express themselves and actually mean something because what the jargon means to your particular corner of the world is not what it means. in mind. And so I like to think of of words, it's like how we build a query set. It's like every time you add a modifier to it, you're modifying the results. I mean there's subtle there might be a subtle difference, but that could be a very significant difference. So it's like, I would just add that, you know, encouraged to, you know, brevity is not necessarily, you know, always the soul of virtue.

Speaker 3: And and um It's uh I had another idea, but should also

Speaker 2: bye bye.

Speaker 1: You should go to Jacob's talk tomorrow. Um I've I've seen his we we wanted to make sure that we didn't have too much overlap so we know a little bit about each other's talks. So I've seen his notes and I think that you would particularly enjoy it. But but yeah, I think that there's there's a a tension between Um, you know, being accurate and being brief. And sometimes sometimes being fully accurate means using maybe more words than you would like to. Um

Speaker 3: and as a Perl expat, I have to say saying self-documenting code, if you believe it that, um, I have a bridge to sell you. Fairies do exist.

Speaker 4: Are there any are there any other questions? If you would like the micro the microphone can come to you. You do not have to come to the microphone.

Speaker 5: I have a brief question, but I can probably project well enough to reach the most most of the room.

Speaker 6: So uh one bit that I struggle a lot with is coming up with useful intuitive names for classes and functions. Uh because to make them manageable in the code, I want to keep them nice and short and like just one or two words. And uh to make them accurately describe what they want to do, I want to basically put the doc string in the name. And this I this is not just me. I've uh it came up in someone's talk yesterday that Django has a couple of things called meta and a couple of things called options that aren't like So there's multiple meta options combinations that you might run into.

Speaker 6: It's all your fault. What guidelines can you give us on that?

Speaker 1: So and again, I'm pitching Jacob's talk so much. His talk is like exactly that. Um like so if if you if you want to know about how to name things better Um or how to what kind of guidelines to have, you should check out Jacob Birch's talk tomorrow. Um the other hard problem lessons and advice on naming things Um and for for me, I I will say I struggle with that too. Um I I think for function names or for variable names or class names, it's You want it to be accurate, but you also don't want it to, you know, 65 bytes of your 80 character limit is your your function name. Exactly, right. Yeah. Um so um it's hard

Speaker 1: and practice and I think you kind of get used and I think it's easy to get down that trail, right? You have like the one class that is pretty straightforward, and then you have the other class that maybe inherits from that or is referring to that in some way. So you name it in reference to, and then you name another thing in reference to, and then you name another thing in reference to, and then it's just like turtles all the way down and Um and then you have these incredibly long names. And so at at some point um I think it can be better to maybe try to think I think a lot of times whenever that happens it be it be it's because you're naming something in reference to something else. And so you want to say, you know, this function is different from this other function in this way, and that's like your function name. And if you can kind of sense that pattern or sense that that's what you're doing, you maybe you can kind of back yourself up a little bit.

Speaker 1: And that's not the only how that's not the only way that we wind up with really long names. But that's one of the ways that I notice in myself Is that that's the way I wind up with two long names is I'm just re referring and then referring and then referring. So

Speaker 7: All right. Thank you for a lovely talk. So good good English evolves over time, right? Or at least I believe that. I know some people So good English writing evolves, um, and yet uh I'm not intimately familiar with the way peps work, but I believe PEP8 just sits there, right, inert. Do you think that the way we write code and our coding style should evolve over time and how do we go about doing that?

Speaker 1: I think that it can. Um and I I I can I 100% I know a lot of English majors don't necessarily agree. I agree that good English evolves over time. Um that's why I say y'all, you know. I have a master's in English. I think y'all is the perfect plural pronoun. Um Yes. Thank you. If I if I've given any message today, it's the gospel of y'all. But no, I and I I don't know um the particulars about how Pep get changed or like can you submit a PR against a PEP? I have no idea. But I think that those are discussions that we should have. And I I think that whenever Like when it comes to like the Zen of Python, I think that so much of that is really timeless. Um maybe there there are probably a couple of lines in the Zen of Python that could um

Speaker 1: that that would be things that maybe could could be changed over time. Or a couple of things in like PEP 8 that could um that might be less relevant over time. Or maybe we decide that we we don't want, you know, two full space, like two lines after a particular kind of thing anymore. Um those standards change. And but they change over usage too. Part of the way the English changes is through usage. And um so as people wind up doing different things, um like the thing that I hope changes is like the 80 line length, like the 80-byte thing. That is You know, although there are still some people at UT who we're still on a mainframe, so we actually do have programmers who do develop in those environments where it's it's a hard 80. Um but most of us aren't in those environments anymore, so 80 seems a little a little harsh to me. Um So yeah, we can all band together to make like a

Speaker 1: working group to talk about the eighty line length if we want to. No we don't No, we do not. All right. Yes.