To comment or not?...by Veronica Hanus

Speaker 1: How's everybody doing? I see you're still here, so we're gonna call it successful. Yes? Is that how speaking works? I'm wondering how many of you have made a comment to yourselves as you were like within the code itself. You said, oh, I need to make a comment. This is a little note to myself. I see a few hands and then some shy hands. I suspect when we get more comfortable there will be a lot more hands. Thank you. well. So you may have done that for a bunch of different reasons. There may have been a variable that you were scared to change. You could have, say, copy-pasted some section of code from Stack Overflow and wanted to make a quick note about what it did. I see a few grimaces.

Speaker 1: That's my everyday as well. And you or you may have made a choice that you wanted to be able to explain to your future selves because it's easy to forget why you wrote what you wrote. Um but I'm wondering when you made that last comment, did you think that you were making documentation? So, documentation is what allows us our code to be used, expanded, and adapted, and for community to be formed around the software we create. So when you last wrote that comment to your code, why did you do it? You may have been making a note about something that was unclear? And in essence, that's when we go to documentation. So it um so it makes sense that

Speaker 1: the comments that we make now may end up being the guiding our documentation later. And as this comic perfectly illustrates, documentation can cause or relieve programmer pain. You don't want to be this reptile. So comments as docs often different benefits, offer different benefits than the long for readmes that we think of as documentation. They can summarize the purpose of a particular file, which can be really useful to folks doing a deep dive into a new code base. Describe functions in place, give the why for a decision, and lower cognitive load. With all these reasons to use inline comments, you may think that we'd be using them everywhere.

Speaker 1: But what's the problem with that? These things are all true. While testing if we are using it can point us to uh possibly outdated function stream strings, there's nothing that I can that I found that will help us keep our inline comments. So too many comments does in fact point to unclear code. And something that we forget. About that refactoring comment that's up there, a comment to our little stick figure man about refactoring, um, is that Refactoring happens often when, you know, as something that you need to do hurriedly before you

Speaker 1: uh you know finish a PR or And often is pushed aside in so that you can do new work instead. So if you don't have time for feedback like built in to your um to your workflow, you may end up feeling that that that important time spent refactoring is a nice to have. So you end up refactoring when you can't stand anymore where the problem has grown to be so large that it must be taken care of. care of right now. So if you find that refactoring has pushed the back burner again and again, you may have to work yourself up to wrapping your head around what has become very old code. So when you can refactor, you might have to put yourself in a good mood, go to your favorite room in the house, play your favorite concentration music softly, and draw yourself a relaxing bath.

Speaker 1: I'm glad you all appreciated that. Um so you know this this refactoring step Which we which we know is important. Even as experienced developers, we often aren't in a position to make time for the way we should, and newer developers have even less ability to take that. That step. And this comment take comic takes on a lot more nuance if we consider those rotten comments that we're always worried about. So the message is no longer, hey, docs are important and they're what we build community on, but it's also, you know, having that outdated comment that we didn't take care of

Speaker 1: is going to mislead. Um and in fact there have been real losses that could be avoided by a well-placed inline comment. In my research, I was told about an incredible loss of data due to a developer changing a value unknowingly. And you know, that leaves me wondering, could a clarifying comment have saved the day? And if we think about our newer devs, the devs who may be using their inline comments as a form of documentation, we see that we're sending a very confusing message. We're telling folks that they need to keep their code dry, not repeat themselves, but also that undocumented code is unusable.

Speaker 1: And when your forms of documenting are limited, that that really puts you in a, you know, how am I going to find the right commenting style? I want to do things the right way, but what is that? So we're going to look at some comments, some dirty, terrible, filthy code, and it's dirty, terrible. filthy comments. So we'll have a little fun at my expense. Let's see what happens. So in this first example, I had used a tutorial to kind of kickstart this project. And I thought, you know. I'm a scientist. I should be citing all my sources, and I put that tutorial right at the top.

Speaker 1: How do we all feel about this? Was this like an okay comment to have within my code and it gets to stay. I see one thumb up. Do we get some thumbs down? I see some thumbs down. Okay. There's some disagreement, but a whole bunch of quiet people. Can we try that one more time? All right. Hands up if you think this is an okay way to use inline commenting. I see a bunch of hands. Hands down, hands up if you think this is not okay. Please don't do this ever again, Veronica. For those of you with your hands up right now, I'm about to show you something even more disgusting Alright, so this was my first time using beautiful scoop it

Speaker 1: soup and I was using it to uh scrape this website and show me whether my favorite student organized climbing wall would be available during my lunch break. So, you know, a student would come and it was kind of hit or miss because students. So it would they would come and you know update their app website thing, whatever they were using. And often I would miss these climbing wall hours because I hadn't checked my um checked the website right then. So I was gonna make myself a scraper. It was my first time using Beautiful Soup. I did not know what was happening. Um so I s

Speaker 1: made comments about what I needed to do. I found I'm Wrote some non-working code, decided that should be commented out in case it would be closer to correct than the code that I would write next. Um And and I wrote my favorite comment of all time. Um oh it's a list, thank God. Does I assume everyone who's giggling has written a similar comment in their life. That makes me feel a little better. Um and the difficulty with all this is is We can all agree that if we saw a code base and we're thinking of contributing that looked like this, we would

Speaker 1: run out that door. Right? Um so I conf I feel confused looking at this just now. It actually took me a moment when I looked at this slide to be like, ooh, what was I gonna say here? There's too much going on. Um And I think I'm going to skip that and say that we have um so there's some things that we can agree on when it comes to what makes g a comment useful and you know what are some best practices that we can get behind versus not. Um so I'll I'll give you guys a moment. Stock strings, we usually like those, right? Outdated comments, bad news.

Speaker 1: And my favorite, too much is too much. I don't know what that means still. So there's a lot of variation in what we consider best practice for common. And the explanation is clearly enough, clear enough. There's different styles of commenting, people use different languages, there's different standards within companies or fields. Um but we can all agree that comments, if used properly, can be an invaluable part of a code base. But what is using a comment properly anyway? We may find that labeling our cats is actually really useful. Um

Speaker 1: And of course when we find ourselves in these situations, we go to the internet. And the internet has some advice. Um has anyone else here seen a good stack overflows dry SmackDown? Well, okay, I hear some people not seeing these dry smackdowns, you need to go to Stack Overflow and you need to ask, like, when is the best time to comment? And you'll get a whole earful and it's really fantastic. And we'll see. Some of that later. My favorite comment, because I went out and I tried to find like, well, what is advice for when we have these comments that we shouldn't be using? And my favorite piece of advice

Speaker 1: I'm still working on that. Um And all this comes to me, it kinda it it you know it kind of looks like you know they're telling you, oh, stop, but they're not telling you what you need to be doing. Um and once I started seeing this attitude. I started seeing it everywhere. Even in learning-oriented, beginner-focused communities. So And it wasn't until I started pairing with people who were a lot more experienced than me that I that I realized that there's so much more nuance to what I um than what I was experiencing, you know, sitting at home tapping her along on um you know

Speaker 1: being a person of the internet So when we ask um when are comments too much and when are they not enough, you know, we may ask a whole, you know, Give our give some background, really helpful, doing everything that we can, and the response that we get looks a lot like this. And it's really important when we see this kind of discussion, there's always a grain of truth in the person telling you. Yes, this may have been discussed to death, and it may be that there are all these best practices that people are should be following, but maybe they don't need to be following them right away.

Speaker 1: Do you all remember when you were new programmers and you first learned that you could put that nice little hashtag and the interpreter would just keep on rolling and you could write whatever you wanted in there. I see a couple of nods. Y'all are very shy. I know. It's fine. But like the the truth is, is these, you know, when you're first getting started and you realize you can do it, these these comments are magic. You're writing a secret note to yourself in your code. The thing that is confusing you, you can make an outline, you can like explain what something means. It's it's magic. And I I only saw a few heads nod

Speaker 1: saying that they remember that moment. So the rest of you may be like this. And that's okay too, but I I want you to like come come back with us and like try to try to remember what that what that moment was like. And I want to remind you that when newbies are learning how to program, they're overwhelmed by trying to learn four, five, six different things at once. And you know, Diane here says, W, I don't know what the fuck I've done tonight. Like, I committed some stuff to get. I did some things in JavaScript. What's going on? Um And this is this is where a lot of people

Speaker 1: are at. And what happens if we tell this person that only clean comment-free code is okay. They're not able to do all these things that they may have been using commenting as an aid for. And the more I thought about this, the more I said, okay, we we need to address this. You know, we're we tell people as they're more experienced that they need to be writing. documentation, but yet when they're first getting started, we say those things you might be using as your first helpful docs, those are bad. Those mean you're a bad programmer. Okay, thanks. Bye.

Speaker 1: So I asked Twitter, and I'm extremely popular on Twitter. So when I ask questions, people answer, and this time an entire nine people answered. Um And you know, nine people, you can't get a 50-50 split, but I got as close to a 50-50 split as you could, and it really appears that either Does some number of these nine people think that they've written dry code since the beginning of their days? Or they have very short memories, and I see one person shaking their head ex enthusiastically, and I am, you know, encouraged by that. This is a lot. So I said, so I said, wait a minute, first

Speaker 1: off, um, nine people is terrible data, and we can't do anything with that. So I I made myself a real survey and started asking some real big kid questions. Um And we we're gonna look at those results now. We're gonna skip a few of the slides because I spent too many times too much time saying words earlier. So I I tried asking a series of questions that broadly were, are comments helpful to you? And are they helpful to you in a variety of ways? Like, you know, I asked, comments can help me remember what my code does. And 10 is a strong agree and one is disagree. Um this is a hundred and uh a hundred and sixty-seven folks responding.

Speaker 1: Um so so pretty strong agreement and we move on and that's Let me, I'm sorry about that. So comments help me clarify my thinking. We're in agreement again. Comments can save current and future developers time. Everyone's like, hooray, we all think this is true. Everyone in this room thinks this is true as well. Yes, probably And then I asked, comments are helpful to an individual contributor building a project but should be deleted before the project is shared. This is like how much shame do we feel in our comments?

Speaker 1: Was really the question I asked. And I was really delighted as someone who had been told that you really should like remove your comments before putting them to GitHub if you want to ever be taken seriously Like apparently I'm the only one to have that experience and that brought me so much joy. And this is something that a lot of uh people pointed to. That function level comments, those those doc strings, those are okay, but inline comments are clutter. And the folks responding to my survey were, you know, a little bit split, but shifting more towards, you know, maybe inline comments are okay as well. They're disagreeing with that. And then here's here's the real moneymaker. Um I said clear code is self-documenting.

Speaker 1: And doesn't need comments. This is like what all our friends doing those Stack Overflow dry smackdowns I was talking about. This is their line. And You remember how strong the, you know, comments are good agrees were. This is really spread out. Do you see this? This is like. How there 's there's a whole lot of disagreement here. And the thing that the thing that this brings up for me is is that means that As much as we all are likely to use inline comments and find them useful, um as as uh as folks have said earlier. We've or some of us responding to this survey

Speaker 1: have really, you know, also internalized that your code should be self-documenting and you shouldn't need these comments, however, we're all using them. Um I asked uh respondents for short answers as well. And the thing that struck me, I'm hoping to do you know, more more analysis of these of these answers because people wrote me like whole tomes, they described like what they had done at various stages of development. And it was really neat because the uh the people who answered varied in experience level from one month all the way to, you know 30 odd years of programming. So there's there was there's quite a

Speaker 1: quite a breadth of experience there. So what what is um the best use of comments? We see our cat again. But you could also create whole man pages instead of having inline comments. My favorite use of comments in the whole world. Some folks are creating ASCII diagrams to like describe where their code what their code is doing. You know, if you have a complicated system, it can be really helpful just have a little you are here Um and there's a generator linked at the bottom there if you if you want to use that. And one thing that struck me when I was researching

Speaker 1: for for this talk is that the idea that when we look at the our code, it's More than just software. It shows us like what problems we care about and like where we are as a community. You know, it shows us our shared understanding. So if I had to say that in a like very tweetable sound bit, I would say that comments really teach us about ourselves. They show us what causes us confusion, what needs to be documented, and yes, something. times what needs to be refactored. So what can we do to support newer programmers as they're you know going from the magic of comments to developing more nuanced

Speaker 1: um documentation strategies. I really think the bottom line here is empathy, being able to advise people where they're at and you know while pointing them to what they're likely to want to do in the In the future. Someone pointed out to me that when you're doing demos, when you're up here giving talks, if you had a comment to your you know within the code as you were writing it, you can leave that in. You can normalize that that is an okay part of an experiment. It's important to remember that someone, you know, the way you're uh the way you're presenting um on commenting or other exper documentation experiments that people are doing

Speaker 1: is going to not is going to lead to affect how people think of documentation in the field. future like what kind of developers are becoming so thank you all for coming and um This is me. We should have Okay. Any questions?

Speaker 2: We have time for one, maybe two questions if anybody has something in mind.

Speaker 3: Have you ever used the Django Spaghetti and Meatballs package?

Speaker 1: I have not, but I'd love to hear about it.

Speaker 3: Well, I've heard about it. I'm going to try it here on my project in a little bit. but it basically does uh object entity mapping maps automatically for all Django models. At least that's what I read. So

Speaker 1: I have not used that. Um I think the name is incredibly clever, especially as someone who has written a fair share of spaghetti code herself.

Speaker 4: Um thank you very much. Sorry. But there might be people who aren't very familiar with cats. or don't speak the language or or get easily confused with other animals or something. So also depends maybe who's going to be reading The code. Sure. And um use the case.

Speaker 1: Do you want me to go back to G sites?

Speaker 4: Well you mentioned in the last slide that empathy is very difficult. So w I I'd be really interested to know what you think about how we should think about the people who are reading our code and and whether if we start labeling our cats Maybe we're helping somebody that we hadn't realized needed to be helped, or maybe we're getting in the way of people who find that unnecessary information. Do you have a suggestion?

Speaker 1: Sure, sure. I think it's important to consider um what language you're typing in, uh uh what what language you're working in, um like how strongly typed it is, can give you some guidance as to you know how explicit to be. And one thing, one bit of advice that, oh, if I can remember it and it doesn't run out of my head right away. Um one thing that I always look for, like when I'm, you know, talking to people who are who I might be working on a project with is I say like, do you pair program together? Like do you sit down next to each other? because and like see how people think about their code because that really gives you the opportunity to

Speaker 1: um t to have someone express confusion in a way that is lower risk and um and you know doesn't need to be you know, solidified in code. And so if you find that you're working and all of your junior developers have have uh pain points, that would be an excellent time to say, we need to make this more expensive. explicit. And I it's it's interesting that you you brought up like, you know, having different words for cats because I've uh known folks who have done experimentation like what if we wrote You know, what what if instead of writing in English we um we were to write code in other languages? Like would

Speaker 1: um like would that change how people thought of the code? And that's I think I think it's a really interesting thing. to uh to think about. Um yeah, I hope I hope that helps.

Speaker 2: All right. Thank you so much for coming. Thank you, Veronica. You can take a nap on this towel. Thank you.