To comment or not? A data-driven look at developer attitudes toward code comments

hello perfect wonderful um so to to do this talk I conducted a survey so I want to do a quick straw poll among us right here I'm wondering all right testing one two three little - 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 gap we've all been there it's even 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 in the future you just oh it sorry 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 enlighten comments all over the place come on slide please thank you all right so we're gonna 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 and they're learning as they change direction look up terms find coat samples so in this first example what do we think the tutorial of 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 beautifulsoup to scrape a website and send an alert when her favorite on-campus climbing wall was open and you see there's this little little boy badly colored green square that would say open if we could see it but you know our hero has not used beautiful soup before and the notes that she made to herself lists 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 and notes expressing her confusion including my favorite comma 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 I when I was pulling out this example more 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 yeah 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 it 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 community to be formed avoid causing other programmers pain so as I was approaching my own comments as Docs strategy I try 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 there 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 have be able to maybe clarify any any tricky situations you had to just 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 you know benefit from having all their work in front of them it also could serve as a note 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 balance now I'm sorry I think this will be hard to see you want helpful comments but not distracting oops helpful comments the not distracting ones and it's possible like this comic claims that you know the kind of hazing around figuring out when adopt I wouldn't comment is helpful documentation and when a comment is fluff and should be avoided is a bit amazing 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 are 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 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 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 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 docstrings 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 or 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 and I put this nifty little hashtag the interpreter is gonna ignore it and I can put whatever I need there nobody just me remembers that okay okay I see a few kids 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 in 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 you know code hoarders among us comments holding code that we we don't use anymore but we aren't quite ready to get rid of yet even even one person added comments that record the URL of a web of the website where they had found some insight they had Stack Overflow done that copypasta thing and they it wasn't theirs so they wanted to tell it to like show what they had done and not okay so there is a lot of different ways of these folks found 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 forgot I don't really know WTF I've done tonight I committed a lot of stuff to get something-something JavaScript you 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 and we tend to forget that this person needs aides 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 to 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 you're going to hear if your code has too many comments you need to effector 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 um you should not use comments why are they there in the first place you should only use like 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 there's a Nantucket I don't know how that feels good okay it doesn't feel very good y'all are less emotional about this tonight all right so I I want to stack overflow and there were there were too many things I could have made a montage but um instead I'm just gonna 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 up close can you imagine a jerk on Stack Overflow getting a lot of up to votes so I don't want to pick on this one jerk cuz 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 was a beginner beginner and then a slightly more advanced beginner like looks down on the beginner beginner and says like me and Nick 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 9 respondents do you know how not statistically significant nine responses but I asked hey Twitter have you always been dry or is that something you came up with as you progress as a programmer and Twitter well I got nine respondents and they were split almost right down the middle if I'd gotten ten that probably would have been right down the middle and I was a little hurt that so many people said they were dried 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 the survey I'm sorry 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 get 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 they're commenting and changed over time or to write after each question and they they wrote I'm going to talk through and summarize as we go along because I made the mistake later and putting too many words on slides as one dust and so I'll share those 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 you using my comments or do you comment out unused code shamefully and I expected because I had so many dry focus on Twitter I expected I did not expect so many people who say yes I using blank comments 90 let's see what percentage is that it got cut off 50 something percent I didn't expect that about and people said some words my favorite comment was someone said as a child and one one really neat thing about this survey and I want to dive into this data more so there will be 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 I was and and it's a really nice spread and I am really glad that I that I put in the effort to you know cast such a wide net and that people responded and really had like strong feelings about comments that went on for paragraphs and talked about their childhood commenting and how they've 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 through you know four years ago so some folks said I used I comment on used code Co comments clutter code so we've got a we've gotten on a non comment personal room and and it goes on so I asked me would you adds comments because remember I had that long list of reasons for comments earlier that my my newbie buddies were using so I said how about how about scoping do you have it to-do list in your comments does it help you experiment do you add them as you're completing a program and the surprising number of people said yes it does help me experiment I'll start writing a piece 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 than 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 off line 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 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 aid that they use anymore and it's possible that there are whole lot fewer newbie programmers who are using comments in the way I and some of the people I've mentored have 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 that's a pretty wide tale considering what we were seeing before and when I get to clear-coated 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 what can we do a lot of us are really experienced we're probably mentoring they'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 asking to show the state of your game in June 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 you're overwhelmed learner Ave I advised 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 they were to think about what comments were again and we said what if comments are dogs 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 comments 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 you [Applause]