On today’s episode, we are joined by special guest, Veronica Hanus, to talk about developer attitudes to comments. Veronica is a second career, self-taught developer as well as a tech public speaker and has also done some of her own informal research related to the use of comments. There is often so much confusion around commenting, such as misunderstanding the effect that it has on code, who will be able to see it and even what its purpose is. Along with this, there is also a widely held belief that comments equate to badly written code. Veronica, however, believes that if we look at commenting differently and see it as a part of the document building process, rather than a reflection of the quality of the code, then more people will use them. Comments are an extremely helpful educational tool, both for new and more experienced developers, so removing some of the stigmas around their use would open up many more learning opportunities. For all this and more, join us today!
Key Points From This Episode:
Transcript for Episode 131. XYZ. Developer Attitudes to Comments! with Veronica Hanus
[0:00:01.9] MN: Hello and welcome to The Rabbit Hole, the definitive developer’s podcast in fantabulous Chelsea, Manhattan. I’m your host, Michael Nunez. Our co-host today.
[0:00:09.8] DA: Dave Anderson.
[0:00:10.8] MN: And our producer.
[0:00:12.0] WJ: William Jeffries.
[0:00:11.9] MN: And today, we’ll be talking about the attitude that people have towards comments as developers.
[0:00:18.0] DA: Because developers are full of attitude.
[0:00:20.2] MN: Yeah, some people are always angry that there is, comments.
[0:00:23.5] DA: And snapping.
[0:00:24.6] MN: A lot of attitude towards these comments that gets ran in your code base. We have a special guest today. We have Veronica Hanus. How’s it going Veronica?
[0:00:34.0] VH: Hey, how are you doing?
[0:00:35.1] MN: Doing fine, yourself?
[0:00:36.8] VH: Pretty good. I am Veronica and I am a second career, self-taught developer and especially being self-taught, I have always been very eager to like do things the right way and use best practices. And I ran into a lot of confusion when I started learning about how to comment within code. So, that took me on a whole commenting adventure.
[0:01:04.9] DA: Yeah, especially using the word best practice, that’s like – was it like every time you use the word best practice –
[0:01:13.0] MN: I don’t want to say it online, a dog dies every time you say best practice, you know, Dave and Andy mentioned in a previous episode, it’s pretty sad.
[0:01:23.2] DA: Yeah, because like I don’t know, people have feelings about comments as much of anything else. Sometimes people are like, “I hate comments or I love comments,” and you know?
[0:01:33.9] VH: That’s one thing that brings a lot of confusion because when someone is like first you know, if you can remember the time when you realized, “oh, wait, I can put some symbol in front of this text and like the interpreter, whatever is not going, that’s just a note to me now,” like that’s magic. “My god, I don’t have to store everything in my brain, I can put some of it into my editor, but it’s not going to affect how my code runs.”
Like that’s what that is. But you know, just as soon as you do that, if you have somebody sitting beside you being like, “your code’s that comment’s going to rot, that’s going to be no good in two days,” you know, there isn’t really space to use that as a learning tool, you know, I’ve seen people use comments in lots of different ways and like you know, tell me what you’ve seen?
[0:02:28.1] MN: There is definitely WTF is this shit, that’s the best one. I think Dave, you have read one before where it’s like, do not touch, that’s a big one.
[0:02:40.5] DA: Yeah.
[0:02:42.4] MN: I did this while I was drunk at five AM.
[0:02:45.9] WJ: A lot of apologies like, please forgive me for this code that I wrote.
[0:02:49.3] MN: That one’s good.
[0:02:51.0] VH: I actually want to touch on do not touch as a comment because I hear like, you know, the frustration piece but also, that’s real. Especially it can be helpful to go back and be able revisit, like when you’re learning and you’re like really at this stage and I’ve had people approach me, especially after I’ve started like speaking and writing and doing things more publicly. People approach me and say, “I’m at the point where I’m doing tutorials, how do I get to the point where I can start to string those skills together and make things? Like I can’t imagine breaking down a project,” and when you’re at that point, that’s a really good time to overuse comments.
Because to just like put best practices in a box somewhere for later because you can break down those pieces and give yourself instructions, you can explain like what you’re understanding was at a specific time, if you copypasta something from Stack Overflow, you can say, “hey, this is where this came from and I didn’t write it and I don’t know what it does.”
[0:03:56.1] MN: Yeah, I like that one. “Hey, here’s aa reference as to why I’m doing this and then it’s like the Stack Overflow.”
[0:04:01.8] VH: I’m coming form an academic background and my urge to do that is so strong, I can’t tell you.
[0:04:07.6] DA: We’re excited page.
[0:04:09.6] VH: There are a few things I fear more than like going back and being like, “I don’t know what it does and I don’t remember writing it because you never wrote it Veronica!” You know, not realizing what state I was in and what was going on takes me like one step further from understanding what it does.
When you’re in that overwhelmed, learning state. Now, we all kind of like move towards that closer to or towards that depending on like where we are in any project or like learning of a new language, et cetera. I think every time people bump into something, that’s like a big new thing to them. They take a few steps back and they need some more of those tools.
[0:04:57.0] DA: Right, yeah. I do like kind of when I’m working, I just feel blocked, like you can just write out in English. “This is the part where we do this.” I’ll just you know, close my eyes and imagine I’ve already figured this out, “but X goes here.”
[0:05:12.2] VH: One thing that’s really interesting to me is where we’re so accepting. We want – one thing that really motivated me to look into this topic is as I started talking to more experienced developers, folks who had been in 10 years and stuff, they always said, “well,” they always had a more nuanced approach to comments because I’d be like, “what gives, what should we be doing here?” And they’re like, the answer was always, “well, you know, it kind of depends.”
[0:05:37.3] MN: Yeah, it depends.
[0:05:39.1] VH: And then there would be this long, nuanced explanation and you could get somewhere with that conversation. But I was seeing, in forums where developers would be a kind of about the same level. You know, I’d see things like, “I have six months more experience than this person so I’m going to kind of let them know that I know something that they don’t and tell them that they should not be using those comments and their code had better be dry.” And you know –
[0:06:07.9] DA: Or the opposite experience where someone has been developing and they got burned by working a system that was just so horribly hard to understand that they’re like, “I need these comments like everywhere. If you’re writing something, you need to tell me in English what it does.”
[0:06:24.6] VH: As I started seeing these attitudes and seeing like all the ways that folks, when they were like free to use comments would use them and kind of see like the smack down happen over and over again. I was like, ‘what are we doing? Are these like more experienced developers? Have they forgotten what it’s like to be like that overwhelm person? that’s like, ‘I’m trying to figure out everything at once you all, can you just let me have this?’” And so, I started asking some questions and I ask Twitter like, “hey, did you all always write dry code?” And like, nine people responded because I’m very popular on Twitter.
And you can’t do anything that’s like a sample size of nine but it was split down, well, not down the middle because they were nine and not - but if there had been 10, it would have been probably split down the middle. It was like, almost 50/50 and I was like, “okay, if nine people can’t come to a consensus, we need to – what’s going on, I wonder – I just have no data.”
[0:07:25.4] DA: I’m sorry, what was the question again?
[0:07:26.5] VH: I asked like has your code always been dry or something like that. And yes/no. People were like, you know, 56% of people were like, “yes, I’m always dry from day one.” And I was like, “you don’t remember day one because we’re human,” and I assume they have very short memories.
[0:07:47.6] DA: Yeah, we had agreed discussion on dry too, it’s like, you know, what does dry really mean? Is it the dry function, the dry –
[0:07:54.7] VH: It’s certainly doesn’t mean devoid of comments like if clear code just means no commenting that that just means you’ve made and perhaps indecipherable code. And one thing I ran into when I was first putting things up on GitHub is somebody told me, “hey, if you’re going to be taken seriously as a developer and you're going to be extra scrutinized as a woman so you better like, get used to that.”
“Your code had better be dry. I see you with your comments all up in your files, but now that you’re using version control, we’re going to delete those comments before you put them up and you’ll thank me later.”
[0:08:32.4] MN: I do have a question because I personally feel like I am the individual who tries not to comment, like I do whatever I can to not. I feel like, when I have the urge to want to comment then it means that the code that I wrote isn’t clear in the first place for me to have to want to have that habit of writing a comment in the first place.
So, in doing that, do you – would ensure that code is understandable before you write comments to then write comments or do you write them so that it makes you understand the code that you’re about to read? Because I think one of the problems that people have is that functionality of say, choosing the right lane in a highway.
The logic that was first written could be completely different to it now. And the comment might be stale or what not. I’m just curious, when do you – the answer is it depends, but I want to know when it depends for you too actually write the comment I guess is my question.
[0:09:34.3] VH: Sure. I think the most important piece of what you said I think is like- I think it’s important to remember what you’ll actually be able to do. Like what is going to be supported by your work and the kind of code base you’re in, how much of that code is your, et cetera. When I’m doing – I really like function level comments and like, comments at the level of like, a document, you know, like “this is what we’re trying to do here and this is what it connects to.”
In general, a thing that I’ve seen again and again is like, the comment explaining why makes sense. The code should tell you how and that you know, kind of making that separating those two, I think is an important piece. Now, when I started looking into this topic, I made this survey in 170 wonderful people, you know, sat down and answered all these questions and yes.
[0:10:36.5] MN: Shout out to the 170.
[0:10:38.0] VH: Right? Thank you developers and it was really great because there were people who had been working for 20, 25, 30 years who responded and folks who are like, “I stared doing a line by line tutorial, one month ago.” A think that I saw is, I saw over and over again, it depends. I saw that people really cared about comment use like whenever I gave people room to like, you know, write a couple of paragraphs.
I would get a couple of paragraphs that was a quarter half page long. I had one person start of like, “when I was a child, I used to do this in commenting and now.” I’m like, “were you actually a child, no. I must know. Did you start programming when you were eight as people have now?” Can you imagine?
[0:11:31.1] MN: Man.
[0:11:31.9] VH: Like we’re there.
[0:11:32.7] MN: Yeah, it’s the future.
[0:11:34.3] VH: Or is this like your programming child self which is how I think about myself from like five years ago. Like, “oh, look at her!”
[0:11:45.4] DA: Maybe six months ago for me. Get in there, still had a beard but –
[0:11:53.2] MN: Baby David with the beard.
[0:11:54.5] VH: We are all baby Dave with a beard, figuring out something new at some point. And one thing I was curious about is how – do we all want to work with and be the sort of developers who create docks where the documentation is like part of wiring the code and even if we don’t have space for that at work, we know it’s the right thing to do.
How does this idea like fit in with the idea that code commenting is bad because that is you know, especially to those newer developers that is a form of documentation and certainly, when I was transitioning from like, “I’m doing a tutorial,” to like, “I’m making my own project,” those comments told me what my documentation needed to be. So, you know, that journey for me made me really wonder like, “are these things connected?” I’m still playing with the data that came out of that survey but one thing that’s super clear so far is when I was asking questions.
“Are comments good for this? Are comments good for that like do you enjoy using comments? The folks who responded are like pretty strongly pro-comment.” And I asked, I separated like, “how about in line comments versus like, you know, f function level comments?” And I figured there would be a big split there, but some 60 something percent are like, “yeah, I use in line comments every day. It’s part of how I do things.”
[0:13:16.4] DA: I wonder, is there like a different like style like, people were like, “yeah, in line comments but boo, function comments?” Or people are just like, “yes comments all the way or were no comments?”
[0:13:27.5] VH: I asked a few questions specifically about in line versus function. And on those, a whole bunch of folks were like, “why not both?” There were some folks that are like, you know, “in line isn’t really what we want to be doing.” But a surprising number and like given what I see online, I was like, people will be okay – there’s lots of things that change, how people respond to a survey, one of which is like, “is this practice considered good?”
If it’s like a shameful thing to do in line comments, you’re going to go to that survey and be like, “probably I don’t do inline comments,” even if you did 50 of them that day. And so, I was like probably the number on that will be low but it was like you know, in the 60% or something like that where like, “I use in line comments every day. No shame.”
[0:14:18.5] DA: Looks like safe space.
[0:14:20.6] VH: Exactly. My survey is a safe space everyone. Please answer honestly. So, that was something interesting that came out of that. But the thing that I saw that kind of you know, became a big take home for me is like, there was so much like, “yay, comments are good.” And then when I asked a question like, “clean code is self-explanatory and doesn’t need comments.”
All of a sudden, that strongly skewed towards yes we agree, just flattened out. There’s no agreement among my respondents. Like, none. So, even though the folks who responded to the survey are like strongly, “I use comments, they’re great. I use them for all these different things.” Apparently, we’ve internalized that comments are bad, even though we know they’re good and helpful to us in all of these ways.
I think there’s something to think about and maybe if we shifted the way we thought about commenting within our code to like – this is an early form of documentation, maybe we would come up with tooling that would help with code rot. We could like, find ways to work on this and that’s been one of the major take homes of far from me is like, “we really don’t know what we’re doing, there’s a whole lot of nuance in this and it’s like, hard to learn when you're figuring everything else out.” And then at the end of the day, you know, even the most experienced among us are like, “well I use these things but also, maybe I shouldn’t be?”
[0:15:57.5] MN: Right, I mean I think like the idea, to me the idea of like using comment and code being bad is because someone else like told me. Like I tend to –
[0:16:08.5] WJ: But why? So, let me play the devil’s advocate. I like to make an argument.
[0:16:13.0] MN: No, no –
[0:16:13.8] VH: You’ve been really quiet over there.
[0:16:14.9] MN: William is waiting for his moment. It not all clean code.
[0:16:18.6] WJ: Just like people told me to not use.
[0:16:21.0] MN: No, it is like if I were to right now I am sure that if I had a method where I had two line comment over the method people will be like, “Yo, we get it. You can delete that. That’s fine we don’t need that.” Or like, “Oh that’s bad, why do you need to explain it when the code should be self-explanatory,” is like the idea. But if I had my old project yeah, I’d comment the shit out of all that because it is easier for me to read it and I make my own.
[0:16:45.7] VH: I actually looked really hard for what can people who write lots of comments do to make their code better and what can we do about that and the advice that I saw again and again is it time to refactor, which is great if you know what refactoring is because when you are learning, you might not yet. Or you might not really have a sense of what that means. And two, the other advice I got that was just golden was code better.
Like you should be better at this. And I am like, “Oh, okay, well I’ll just go back to my office and work on that like it would be fine.”
[0:17:25.9] WJ: Yeah, I mean that sounds like maybe not the most positive way of doing it. I mean to me it is like –
[0:17:30.4] VH: There it is not always the positive voice.
[0:17:34.4] WJ: Yeah, I think that most of the time when people talk about comments particularly in line comments as being a code smell, that you know if you feel like you have to explain what a thing is doing in English that seems like an opportunity for refactor and opportunity to clarify. And often you can get the same value out of extracting a method and then the method name explains what it does and now all of a sudden when you’re debugging, you get to leverage the power of the language itself.
And in your Stack trace, it is actually going to show the method name what shows you exactly what it does instead of having to dig through and find, “Oh, actually somebody wrote this explanation, you know six months ago.” And I think we’ve all had the experience of being burned where you go and you read the explanation and it says what the method did six months ago and actually now the method is something totally different.
You know I think these are some of the arguments that come up against comments. And it is not to say that if you are beginner that you shouldn’t be able to use all of the features of language and even for an expert like we are all professionals here like, “let’s give everybody sharp tools and allow the professionals to use the sharp tools.” And yeah, it is possible to cut yourself with the comments, but you know we trust ourselves to make judgment calls.
I think there are times when it is justified. I think one example is on a project a few years ago and there was one account that was special.
[0:18:59.7] MN: The special one.
[0:19:01.0] WJ: One customer who constantly complains when standard, like a normal feature acts the way that the normal feature is supposed to act. And they just got so many complaints about it that eventually somebody winning and like hard coded that account number. There is a short circuit that prevents the normal behavior and then in the comment they’re like, “Okay this is obviously a terrible hack in the code, where we just short circuit if you know the account ID is just one, but realistically this the easiest way of making this customer happy.” And you know probably –
[0:19:35.3] DA: Right you just want this problem to disappear there.
[0:19:37.7] MN: Tell Bobby to stop complaining that is pretty much what it is.
[0:19:41.0] DA: Yeah. Dear reader, you may look at this and think what a terrible person. Why would they do this? But I can assure you. I had a very good reason.
[0:19:49.5] MN: I think the other example that is other example that I was brought up earlier is Veronica mentioned when you copy paste something on Stack Overflow. Like that definitely this, “yo, I found that on the Internet. You want to know more about it, go there. This works, leave me alone.” That one is always good.
[0:20:05.6] DA: I also like comment that are on regex too. It’s like, “show me your regex.” It is like, “how am I supposed to know what this is. What the heck is this thing?”
[0:20:15.6] MN: That is definitely it, yes. Yeah.
[0:20:18.8] VH: That is a whole other language.
[0:20:19.9] MN: Yeah it is.
[0:20:21.3] DA: Yeah, I don’t bite on it. Is it regular? I don’t know.
[0:20:25.3] MN: Just let me know, you have a very long string, very long regular expression, tell me what it does.
[0:20:30.9] VH: If it is going to take me half an hour to figure out this line does, like just please.
[0:20:36.6] MN: Yeah, regular expression yes.
[0:20:38.9] DA: Yeah, I mean you can do the extract method track, that will give it a noun or you know a verb or whatever the heck you need to do but –
[0:20:47.6] WJ: Also, comprehensive test coverage like especially if you have really complicated regex there should be tests that handle all of the edge cases and that works really well is documentation because somebody can go to the test for that method. They could see, “Oh, this is exactly how it is supposed to work and this is how it works in all of these different examples.”
[0:21:03.9] VH: Maybe we should fix the culture on the Internet, so that when somebody comes and they say, “Hi I have been here three months.” They’re like not told to go to some advance blog post that will talk down to them and they’ll be like there is stages. And when someone learns about testing part of learning about testing is like, “Hey this replaces. Now we are taking one tool and we are pulling it from your hands a little bit and we’re giving you this other more powerful tool that is going to be like fantastic,” and you know if we – I want that world to exist.
[0:21:41.0] DA: Yeah, here’ s a new fabulous pair of scissors that you can run with.
[0:21:44.9] MN: The other thing that I was thinking of is like Commit messages are like you can look at the annotation of a Commit message, but I wouldn’t expect someone who is learning how to program to also pick up the knowledge on Git to know that that is a thing. So comments is a great way to introduce taking the English or the language of your brain onto the code that is currently in play and as you’re picking up other skills you can utilize those skills to spread the information in English not just in the programming language that you are writing.
[0:22:21.8] VH: What kind of annotations were you talking about or were you just talking about the body and the subject of the Commit message like you know keeping that detailed enough or was there something more?
[0:22:32.1] MN: Well I think like keeping it detailed like for example, if you were going back to Dave’s example of regular expression like the Commit that you would have introduced that piece of code would explain the thing you are introducing. So, it will say, “Oh this added new feature to identify Visa cards and that regular expression would then be noted in the comment together. So, you know that that is message.
But someone who doesn’t know to look at Git Commit messages may not know that that information is there so you can leave a comment right above that regular expression that says, “this is the regular expression for visa and that is a way to do that.”
[0:23:10.9] DA: Right and that message is going to get buried too in the commit history that moves there or whatever.
[0:23:14.8] WJ: Yeah. It is another form of documentation. I mean I certainly agree that anybody who shits on a developer who has been programming for three months for using comments as a douche nozzle and there are plenty of those in the Internet like you know? That is unfortunate. I would love it if the internet were better. But I mean at the same time I also think you know some of those people where you should have compassion for like the people who were trying to help it suck at it.
Like the people who are like, “I am reaching out and I want to help this person who is learning how to program.” And one thing that I always thought that was helpful to me is like don’t use in line comments but then they don’t explain it adequately and they make the person feel bad and it is like, “oh, I mean this is another person who also needs help. They need help learning how to get feedback.”
[0:23:55.9] VH: So, here is the thing I was that person like at one point I was like it is really useful advice and I am being helpful to people by telling them go ahead and take out all of your comments before you Commit your code because it is going to make you look bad because real developers don’t do that and I have been told that. And I turned around three, six months later and I said the same thing and I was like, probably a shit to a lot of people and I am sorry for passing like what is the 2019 version of the email chain because like you know –
[0:24:27.2] DA: Or it’s like doctors like hazing each other during a residency or something right? You’re like I went through this shitty period, so like I am going to pass it forward like maybe not intentionally but like you know?
[0:24:39.2] VH: One of the memes I found, so I have given a talk on this topic so I searched the internet for memes because what is bigger and better than a meme like really tall behind you when you are speaking? And one of the things that I found was like exactly that is like a two-line comic and the whole point is like maybe this is just some hazing that we have to go through. We all need to be told that comments are shit and should never do them and then later we find out that actually there is all these nuance.
But it is definitely like the difficulty is often people are getting help and advice from folks in circumstances like on Stack Overflow you, it is not always the best answers that get to see up votes sometimes. It is the funniest or the quickest. And like what is the incentive for helping and how much investment do you have in the person because even an online communities where people care and you might hear someone saying like, “Hey, when you get to this stage you won’t want to do this anymore, but I see what you are doing.”
Which is the approach that I would love to see everybody using like you know, “Utopia looks like that in my mind.” But even when those incentive structures are in place where you’re like this is your community and you’re building up people and that is what you are trying to do, I kept seeing this like very black and white thinking around commenting and I was like, “this is maybe like a strange thing that we are especially kind of prickly about.”
[0:26:22.0] WJ: Right I think it is like letting the best get in the way of the good. It is like okay – if you have a massive tangled code that is totally unintelligible, it would be better to have a comment explaining what does than to have nothing and it would be best for it to be refactored in such a way that you don’t need a comment. And if the person who is programming it is not able to or does not have time to get it to that and stay, then perhaps the adding a comment is the lesser of two evils there.
[0:26:51.6] DA: Like one of my favorite comments from an episode that we did, 56 [inaudible 00:26:55] it was like it was a warning message left to all developers who felt enough hubris to try to refactor this piece of the code. It's like if you try to refactor this please then create this count by one for every time that you’ve failed to refactor this and it was up in that you know high 10’s, close to a 100.
[0:27:20.0] VH: And one thing that I run into when I started talking because when I started talking to folks who are like in SRE style positions, where like what kind of risk are you undergoing is like part of their calculation pointed out like look, there are times where something could slip through and you could there have been instances of losing information and like data loss because something went into prod because somebody didn’t thoroughly understand what all was being touched by a piece of code.
And you know this person was like, “If I could go back in time and stick the like you’re standing over hot lava comment there, that would be a time for that.”
[0:28:00.9] MN: So, if you feel like a piece of code is touching hot lava, you may want to consider leaving just a nice comment for the developer who may end up seeing that.
[0:28:10.5] VH: That’s my opinion, but we all have those and are entitled to them yes. But I think whatever it takes personally I think whatever it takes to make your things move and happen easier regardless of what stage you are in your learning and work. That is right way.
[0:28:28.3] MN: Veronica, how can people contact you?
[0:28:31.3] VH: So, probably the best way to contact me is Twitter because I use that as my business card. I am @veronica_hanus and that is H-A-N-U-S. And my DM’s are open. You can do that or you can tweet me and if you are not a Twitter user that is okay, there is room for you too and you can find me at veronicahanus.com or anything similar will work. You can also go to my website and there is a bunch of ways to reach me there, GitHub, LinkedIn all that good fun stuff. You can pick.
[0:29:05.2] MN: Awesome thanks for coming on down.
[0:29:06.7] VH: All right, thanks.
[END OF INTERVIEW]
[0:29:07.7] MN: Follow us now on Twitter @radiofreerabbit so we can keep the conversation going. Like what you hear? Give us a five-star review and help developers like you find their way into The Rabbit Hole and never miss an episode; subscribe now however you listen to your favorite podcast. On behalf of our producer extraordinaire, William Jeffries and my amazing co-host, Dave Anderson and me, your host, Michael Nunez, thanks for listening to The Rabbit Hole.
[END]
Links and Resources:
