 Hello. Perfect. Wonderful. So to do this talk, I conducted a survey. So I want to do a quick straw poll among us right here. I'm wondering, testing one, two, three. Y'all hear me now? As little too far from out there. All right. So I'm wondering, little quick straw poll, how many of us have made a comment to themselves as they were working within their code base? That's amazing. Okay, me too. Not alone. Thank goodness. And there are lots of reasons to want to do this. So maybe you have a variable that you're scared to change. Someone else's code. Do I know exactly what that variable is doing? I'm not sure. Maybe you just copy pasted a section of code from online. And you want to make a quick note? Yeah, I heard a yeah. We've all been there. And it's even easier to forget what the code does when you didn't write it as it turns out. So and maybe you made a choice that you want to make sure that future you knows about, because you know, past you makes choices and future you just, it's hard. So, since we're all on the same page, and we've all worked on these comments, we've come to the right place, we're going to dive into code comments. So with all these reasons to add comments and all these hands going up in the room, we might wonder why we aren't making these in line code comments all over the place. Please. Thank you. All right. So we're going to do a quick critique of two comments. I am shamefully sharing with you today. So what happens when someone who is using learning to use comments and commenting to hold their place and relieve some of this cognitive load that they're going through in their learning as they change direction, look up terms, find code samples. So in this first example, what do we think? The tutorial that I used to start the project is cited at the top. Anybody find that reasonable? It's okay to do that? Do a show of hands? Okay, a couple people think that's okay. We've got some skeptics in the room. Oh, yep, I hear you. Okay, well, I'll tell you what's going on up there. What's going on up there is there is some code and then there's a line at the top that says, I took this code from this lovely tutorial and it is turning into this project. This is what I contributed and what came from the tutorial because I'm an academic and I love citing things. So that's what would be on that screen if my color were a little less off. So for most of us, that comment might survive in a code base and eventually be added to documentation as the project goes. And in this second, hopefully with even better color, we see this person was trying to use beautiful soup to scrape a website and send an alert when her favorite on-campus climbing wall was open. And you see there's this little, oh boy, badly colored green square that would say open if we could see it. But our hero has not used beautiful soup before and the notes that she made to herself list not only what she should be doing, her own little to-do list, it also has code that is commented out. It probably doesn't work. And notes expressing her confusion, including my favorite comment to date. Oh, it's a list. Thank God. So would you want to contribute to a code base that had similar pileups of comments throughout? Honestly, when I was pulling out this example, even more experienced me felt confused just looking at this. If this was file after file, I think I'd run in the other direction. Y'all with me on this one? So before we dive in and we talk more about comments, what makes a good programmer? We need to know languages, methods, there's some amount of knowledge that we need to have. We need to have the ability to apply or problem solving and creative thinking skills. And last but definitely not least, we need to be able to communicate and let's face it, right? Usable code. So we spend a lot of time in our industry talking about that first point, knowing a language and methods. But I want to talk about the journey that I took through the other two, that creative thinking and communicating since they're an important part of the mastery we all desire. So, relatable. So documentation is what allows the code to be used, expanded, adapted, and for a community to be formed. Avoid causing other programmers pain. So as I was approaching my own comments as docs strategy, I tried to see what other people were using comments for. And I found a couple of different uses. You can have comments at the top of a file as a summary. Not all of us use GitHub any other academics in the room. A few? Okay, cool. That's where I come from too. We have these nice little things at the top and it tells you the email address of who you should message if it's all messed up. And yeah, everybody loves having corresponding authors. So, they have comments to describe functions. And then you want to be able to maybe clarify any tricky situations you had to go through when you were writing the code. So this will allow you to later be able to create your own standalone docs, in part using these comments. For folks like me who are very visual and enjoy and benefit from having all of their work in front of them, it also could serve as a notepad, so to speak. And as many blogs helpfully or unhelpfully point out, it's important to tell why you're making a certain decision, but your code hopefully tells you how. So there's some confusion about comments. A lot of people think that no comment is bad code. But maybe this is also true. Maybe you're worried about the bail list. I'm sorry, I think this will be hard to see. You want helpful comments but not distracting ones. And it's possible, like this comment claims, that the kind of hazing around figuring out when a comment is helpful documentation and when a comment is fluff and should be avoided is a bit of hazing that we all have to go through as we learn what the proper balance is. That doesn't sound like very much fun. So we debate. So we hear about comment rot. But it's easy to forget that learners, our people or comments might be helping and that you're not going to be able to decide how many comments or what kind of comments are helpful until you've worked within code bases that use them and been able to see them yourself. So remember, we're trying to create the most usable code we can. If you're always having to go to source, it's going to be a very long day. So I started looking and saying, well, are there some things in all this debate that we can agree on? And there are some best practices that we can get behind. We generally agree. Doc strings should have inputs, outputs, explain the transformation that's taking place. And everyone will tell you that outdated comments, that comment rot, those are dirty, filthy lies. We don't like those. They're terrible. And finally, my favorite advice from the internet, too much. How many comments are too many comments? Well, too much is too much. Thank you. Thank you, internet folks. So sometimes we can agree that the code tells us how while the comments should tell us why. Some folks say, keep things instead of dry, wet, don't waste everyone's time. And that, you know, we put the further critique a line by line commenting may indicate a lack of understanding. So the difficulty for many of us is that there's lots of variation in what is considered best practices for comments as we've discussed. And the explanation is clearly enough. There's variation, different languages, different needs, different industries, and different styles of learning. So companies create their style guides and, you know, decide whether or not we should include doc strings, comments, etc. But we can all agree, no matter what we think about these guidelines, that comments, if used properly, if we can ever figure out what that means, are an invaluable part of a code base. The thing to remember here is that to a beginner programmer, comments can be magic. If you can go back and you can remember the first time you realize, wow, if I put this nifty little hashtag, the interpreter is going to ignore it. And I can put whatever I need there. Nobody just me remembers that. Okay, okay, I see a few hands. All right, well, I was excited. I felt just like this. I was like, oh boy, I'm going to use this all day. So people use this power differently, but many of the new programmers, as I started talking to folks and mentoring, they'll start throwing comments everywhere. I've seen comments for variables, comments that hold questions to ask a mentor later. Comments made during pairing to record some new related bit of knowledge that people are still putting their heads around. Comments used as an outline for code yet to be written. And for the code orders among us, comments holding code that we don't use anymore, but we aren't quite ready to get rid of yet. Even one person added comments that record the URL of the website where they had found some insight, they had stacked overflowed and done that copy pasta thing. It wasn't theirs, so they wanted to show what they had done and not. Okay, so there is a lot of different ways that these folks found to use comments. Really ingenious. And there's one thing as we are pushing folks to do, to be dry and to do things the right way at a time when as newer programmers they're taking on probably more than they can. There's one thing that we forget. I don't really know. WTF. I've done tonight. I committed a lot of stuff to get. Something, something JavaScript. Do you all know this? I don't know. Go back to your commit messages when you're coding too late. You'll see this person come out. You may think that you aren't this person, but you've definitely been this person. And we tend to forget that this person needs aids and resources and the ability maybe to use comments however they need to use comments. So as I was progressing through this stage, and I spent a while being this person because I jumped around a lot, I became active in several programming communities and I started to see a trend. Good code is dry. So if you go online and you say, okay, so I've started learning how to comment and I want, I'm a new programmer and I want to be the best programmer I can. So I'm going to find out the best practices and do it the best way all the time and I'll put that on top of everything else I'm learning. If you're going to hear, if your code has too many comments you need to refactor, you're going to hear the very helpful, you should just code better. No, no, this is real. I went and I searched and this was advice that I got. You should code better. You should not use comments. Why are they there in the first place? You should only use the correct comments and you should know the difference. And only your code matters. Now if you're me or you're someone else who is diving deep and trying to find the best way to do something, what you're actually going to hear is, so the way you're learning is an anti-canon. I don't know how that feels, but okay, it doesn't feel very good. Y'all are less emotional about this than I am. All right, so I went to Stack Overflow and there were too many things. I could have made a montage, but instead I'm just going to show you, and it's hard to read, this person has written a very thoughtful, hey, I'm just learning how to do this and I want to be able to document my code properly. And you know, on and on and they're like, I hear this and I hear that. Can someone give me guidance? Can someone tell me what to do? And you know what the person says? This has been beaten to death. Why are you here? And they got a lot of upvotes. Can you imagine a jerk on Stack Overflow getting a lot of upvotes? So I don't want to pick on this one jerk because there's a lot of them. But this was continuous as I looked and it was also continuous in the forums that I was in. So I started to ask myself, what's what's going on here? Or is this like, you know, kind of a, there's a beginner, beginner and then a slightly more advanced beginner, like looks down on the beginner, beginner and says, like, you shouldn't do it that way. Like, or is there something more we need to address as a community? So I'm a scientist. There are a few things in the world I love as much as data. And so I asked Twitter a question. And I got a whole nine respondents. Do you know how not statistically significant nine respondents is? But I asked, hey, Twitter, have you always been dry or is that something you came up with as you progressed as a programmer? And Twitter, well, I got nine respondents. And they were split almost right down the middle. If I'd gotten a 10th, it probably would have been right down the middle. And I was a little irked that so many people said they were dry from day one because who is. And that really surprised me. And I said, wow, I need to look at this more. And so I went to places that were not Twitter. And I thank you, thank you. I needed that. And definitely when I started this project, I definitely needed that. So I read a little bit about survey design. And I set out into the world of how do humans think? And I made myself a survey. So I asked a lot of questions. I said, when do you use comments? What causes you to use them? When do you add them? Are we all secretly taking out our shameful comments before we add them to GitHub? Okay, I needed to get down to the bottom of this. I saw a couple of knots. It's not just me. Okay. So so I asked, and then I asked a little bit more about people's attitudes towards commenting in general. Tell me how you feel about comments, I said. And what was wonderful in addition to the multiple choice and scale responses that I got is people, you know, I gave them a space to write about how their commenting had changed over time, or to write after each question. And they wrote, I'm going to talk through and summarize as we go on, because I made the mistake later in putting too many words on slides, as one does. And so I'll share those results with you. So what best describes your current or recent use of comments? Do you comment when you're not certain? Do you comment each function as a matter of practice? Do you use single line comments? Or do you comment out unused code? Shamefully. And I expected because I had so many dry folks on Twitter, I expected I did not expect so many people to say, yes, I using blind comments 90. Let's see. What percentage is that? It got cut off 50 something percent. I didn't expect that. And people said some words. My favorite comment was someone said, as a child. And one really neat thing about this survey, and I want to dive into this data more. So there will be more chatter about this data, and at some point it's going to be on GitHub and we'll all get to play with it. But I had survey respondents who had been coding as little as one month and as long as 35. And it's a really nice spread. And I'm really glad that I put in the effort to cast such a wide net. And that people responded and really had strong feelings about comments that went on for paragraphs and talked about their childhood commenting and how they've grown up since then. And in my heart, I really want to know if this person was truly a child when they learned to program or if they're talking about their childhood program or self, which is how I talk about myself from four years ago. So some folks said, I comment unused code, comments clutter code. So we've got a non comment person in the room. And it goes on. So I asked, when do you add comments? Because remember, I had that long list of reasons for comments earlier that my newbie buddies were using. So I said, how about scoping? Do you have a to do list in your comments? Does it help you experiment? Do you add them as you're completing a program? And a surprising number of people said, yes, it does help me experiment. I'll start writing a piece of code. And, you know, I'm not sure if it's what I'm going to keep. And I commented heavily. I see what works and what doesn't. And I know right back where to go to. So more folks are using that, you know, cognitive load, you know, comments as their little cognitive storage bins. Then I expected. And there are more words. I didn't write comments as much as when I started off, because I wasn't confident that what I would say would be useful. Some folks are literally scared of the prose element of commenting. It's comfortable to write code. Writing code is what we value. But the act of commenting is almost more vulnerable. You are writing documentation. You are explaining yourself. It is difficult. You have to if you have pulled something offline that you don't quite understand, it's sometimes hard to say so. And so I had asked a series of questions that said how positively do we feel about comments? And one is disagree and 10 is strong agree. So a whole lot of folks say comments help me remember what my code does. We see a similar distribution for comments help me clarify my thinking, a little more spread out, a little wider tail. And then we get to comments help me learn. And I'm interested to see here what the distribution is for, you know, how many of these folks have just been programming so long that that's not the A that they use anymore. And it's possible that there are a whole lot fewer new B programmers who are using comments in the way I and some of the people I've mentored have been. So that'll be an interesting thing to look at in the future. We almost all agree comments, you know, the good ones will save current and future developers time. We disagree that comments are helpful to you, but should be removed from GitHub. So all those folks who earlier said that they take out their comments before going to GitHub. You're good. Go ahead and add those in. You can show the world. It's fine. But interestingly, when I started talking about clutter and what was acceptable and not, my distribution wasn't quite so clear anymore. That's a pretty wide tail considering what we were seeing before. And when I get to clear code is self documenting and doesn't need comments, we're a lot flatter. So it's clear that despite all this positivity towards comments among my respondents, we're actually still we've really internalized this idea that good code is going to be so clear that you don't need the words. So let's think about what makes a good comment. And I'm so sorry about what you're seeing right there. So what this person did is they're describing the state of their program in a comment. Like they have a diagram and they say you are here at this point. And I thought that was genius. Because guess what? Sometimes it's really hard to visualize what your code is doing at that moment. Some folks will create a whole man page to describe section of their codes. And it's possible that right now, those obvious comments aren't so obvious to you. And as you get better at naming conventions, you won't want to put Post-its on all of your cats. And in the spirit of this quote, the best comments are a huge help, but the perfect comments are not going to come without trial and error. So what can we do? A lot of us are really experienced. We're probably mentoring. We're probably talking to folks who are figuring things out. So our end goal is to support learners where they're at. You want to praise the accomplishments. And instead of saying, hey, it has to be dry. You might say, you know, I see what you're doing there. It's ingenious that you're using ASCII to show the state of your game engine. But you know, some someday you're going to get to the point where you don't need that anymore. So you got to remember your overwhelmed learner, advise them where they're at. And you might want to suggest a deep dive or reading other folks code. If we rethink comments, the thing I kept coming back to is if we were to think about what comments we're getting. And we said, what if comments are docs? Would we be having another conversation? So I want to thank each of you for coming. You've been lovely. I appreciate your participation, especially. So thanks to Pi Texas. And thanks for all the folks who told me their comment stories. I would appreciate if everyone in this room do not take this survey because we talked about some results and you know what that does, right? So don't do that. But if you want a social media, that thing, my handle is there and whatnot. And I'd love to be able to hear from, you know, more folks about their common experiences. So thank you very much.