Today, we’ll be talking about whether comments are considered harmful or helpful. We’re pretty sure that there are many different comments you may have run into in your careers. Comments are something that is really common to every programmer, everyone can relate to them – whether they’ve been tormented or blessed by them. We’ve come across some pretty funny comments in the past like, “Holy crap, WTF is this?” or “Drunk, will fix later,” or “Magic, do not touch,” or just the standard, “I’m sorry.” Aside from their entertainment value, comments can be useful for a multiple of other reasons – such as documentation and setting to do reminders for a team. But how can we utilize comments most effectively to avoid the shame game? In this episode, we discuss how best to use comments for to-tasks, writing tests, the value of user stories, the dangers of tech debt and the almighty perils of the copypasta driven development boys. In addition, we will also discover how scout’s honor applies to code (as well as to developers from the Bronx), why a comment is the only code that can lie to you and how you can quite simply avoid comments altogether.
Key Points From This Episode:
Transcript for Episode 249. Comments Considered Harmful, Comments Considered Helpful
[0:00:01.9] MN: Hello and welcome to The Rabbit Hole, the definitive developer’s podcast in fantabulous Chelsey Manhattan. I’m your host, Michael Nunez. Our co-host today:
[0:00:09.8] DA: Dave Anderson.
[0:00:11.9] MN: Today, we’ll be talking about whether comments are considered harmful or are comments considered helpful.
[0:00:19.2] DA: That’s a double-edged sword.
[0:00:21.1] MN: Surely is a double-edged sword.
[0:00:22.3] DA: Watch out.
[0:00:23.1] MN: Yeah, sometimes, I run into comments and code and I’m like, “Okay, get ready for this, hold on to your seats because I got to read this thing.”
[0:00:32.7] DA: Yeah, I love the comments that kind of apologize for things they’ve done.
[0:00:38.3] MN: It’s just like, “I’m sorry,” the first line is “I’m sorry,” that’s it then it’s like a line break and then like a paragraph of what it is, those are always good.
[0:00:45.3] DA: Yeah. I was looking online for some funny comments and I found one that’s like, you just tag something with like “Magic, do not touch.” Or “Drunk, will fix later.”
[0:01:00.3] MN: I’ve seen “Holy crap, WTF is this?”
[0:01:06.7] DA: Man, that’s like, puts some empathy on it.
[0:01:09.7] MN: Yeah, it’s great. Yeah, I’m pretty sure there are many different comments you may have run into in your careers.
[0:01:18.5] DA: It’s funny too because like, it’s something that is really common to every programmer and everyone kind of relates to. I remember when Microsoft’s source code got leaked for Windows in the early 2000’s, people kind of poured through that to find what kind of comments they had and there was some stuff in there.
[0:01:38.6] MN: It’s not like people were trying to figure out how certain problems were solved, it was like “No, we’re going to check out for the comments. This is where the gold is guys.”
[0:01:49.0] DA: Right. Yeah, I’m not looking for a daisy or a hack or anything. I want the LOL’s.
[0:01:55.2] MN: Yeah, I’m all in for the LOL’s.
[0:01:59.0] DA: Yeah. I mean, I guess there are a couple of things that comments are definitely useful for. A common thing that I see a lot of is like using to track pending tasks, like a to do. Initially, I was kind of like, “I don’t’ know if I’m completely onboard with this” because I feel like you could end up with a lot of these in your code base where initially, it’s good intentions and you're like “Okay, well, I’m going to make this better later” but then if you never actually do make it better, which is like a document of shame that you have to live with.
You’re like “Yeah, I never made it better.” It’s just there. Maybe you do make it better and then no one is like ambitious enough to remove the comment and then the comment’s kind of lying to you. I’ve seen some things where it’s like “To do, please test this” and then as I’m like “Wait, I just wrote like three tests for this thing. Additional tests.”
[0:02:59.8] MN: Yeah, everyone just writes test for that thing and it’s like “Wait, that’s been covered many times already.”
[0:03:05.0] DA: Right.
[0:03:06.1] MN: I do think that if that to do exists for a while then you’re the one who is blamed when someone wants it. I’m sure there are people like “All right, let’s see who wrote this.” And then you get shamed that way. When you have a to do that exists for X amount of time.
I think if you work in an engineering culture that allows you to go after the to do’s that you write, maybe they’re not that harmful but like, 90% of the time, you write a to do and you don’t really go back to it which is kind of not fun because maybe that’s something you wrote a to do for because you were drunk or you wanted to refact or something, right?
You can write a test that covers that thing and you want to refactor it but if you don’t have time to refactor it, maybe it will slip through the cracks.
[0:03:57.2] DA: Right, yeah. I guess it’s going back to the measure thing, like maybe if you’re pushing really hard and you’re taking on that and you want people to be weary of patterns that you’ve introduced that are bad. I think that’s something that kind of changed my mindset a little bit on it because if you’re on a team with a lot of junior developers who kind of are learning the ropes from the things that you have done, that can be helpful to leave a sign post and be like: “Wait, maybe think twice before imitating this particular thing. We’re going to make this better, this is a long term plan.”
[0:04:33.7] MN: Right. One of the things that I thought would be a good idea but doesn’t really work out to my advantage, is actually writing a pending test when something needs to be done. Rather than writing a to do, I would write a test and then make it pending. So that when you run the test suite, you’ll see X amount has succeeded, we have zero failures and you have three pending and you’re like, “Snap, all right, well, we got to make sure that those three pending are actually created and run so that if they fail, that you implement it.”
Then they may stay pending forever because you may never actually build the thing you thought you needed to do in the first place.
[0:05:13.9] DA: Right, yeah. I guess if it’s a feature and it’s not important now, that maybe you’re not going to need it in the future.
[0:05:21.3] MN: We spoke about MYAGNI many a times. Maybe you’re not going to need it, MYAGNI, there you go.
[0:05:24.0] DA: Maybe you’re not going to need it. Soften it up, you know?
[0:05:32.0] MN: Maybe you need it. You’re not going to need it. Yeah, I think one of the things that Dave pointed to, make sure you write like a user story that may force your development team to fulfill that to do.
[0:05:47.7] DA: Yeah, these are both like pretty good alternatives to running a to do in code. You can, like you said, they leave the pending test so it’s there every single time you run it like poking at you or like work with product to have a story and prioritize the future work.
Yeah, I guess like when you’re prioritizing a story rather than writing a pending test, it can be easier to prioritize something like that if it really is a feature that’s like driving value to the users versus being a tech debt. Because then I guess we’ve talked about tech debt in the past and you can very quickly accrue a mountain of stories that is a similar document of shame, as your to do items in the code which is endure instead.
[0:06:36.9] MN: Yeah, you then have to work with your product person and your project manager to work in some of those to do’s and those tech debts that needs to be paid down that’s endure and then by that, by working on that, it’s visible for everyone to know that this work needs to get done. I think one of the misleading thing about to do’s is that it leaves that to the developer to take time out to do that and kind of have to sneak this refactoring in.
If you have it on a jerry board where the entire team can see it, then everyone is aware that this work needs to get done.
[0:07:12.5] DA: Yeah, that’s true. I guess it increases visibility to the people who are prioritizing the work. I used to come to this argument and yeah, I’m going back and forth on this. If your goal is to fold in tech debt and refactor work as you're going as apposed to writing a story and prioritizing that out on the board and testing and queuing tech debt only related stories which is a refactor.
If the to do exist in the code base then people can kind of live by the scout’s rule maybe and as they’re working on the feature, they can see the sign posts that have been left for them and clean things up and also ship – a useful feature.
[0:07:55.8] MN: Right, it could work either way and there are some pros and cons between the two because as you mentioned the scout’s rule, leave it better than how you – what is it? Leave it better than you found it.
[0:08:10.1] DA: Yeah.
[0:08:10.1] MN: Leave it better than you found it then the code will be cleaned eventually. You could tell I wasn’t a boy scout I guess.
[0:08:21.4] DA: They got boy scouts in the Bronx?
[0:08:23.0] MN: I don’t know, I mean, they might, I’m not sure, I never subscribed to one but I’m sure they have them.
[0:08:27.4] DA: Nice. Yeah, I mean it’s a tradeoff as all things. You know, it’s always the end of maybe’s.
[0:08:34.9] MN: Yeah, it’s definitely a pack of fourth. My recommendation is I do like the idea of the visibility across all the teams to let everyone know that this work needs to get done and that we just schedule some time for that. You definitely have to play by ear with your team to know whether it’s the visibility is there for you to do that or is it just – or do you just leave it in the comments and then tear it down soon after? Boy scout’s rule, or rather the scout’s rule, along the way.
[0:09:05.3] DA: Yeah, I guess if you're leaving most comments on there, you do want to make sure that you’re going back and addressing at some point maybe. Purging any to do’s that are no longer needed. They’ve determined to be the MYAGNI’s or YAGNI’s.
[0:09:21.6] MN: The MYAGNI’s?
[0:09:22.7] DA: Like we definitely didn’t need it. How do you pronounce that?
[0:09:25.8] MN: Yeah, we definitely didn’t need it.
[0:09:29.1] DA: With YAGNI’s. Yeah. I guess like the other thing that comments are often used for is documentation, right? Kind of describing the why or maybe the how if something is really complicated for a particular bit of code.
[0:09:46.8] MN: I think that usually, if I see comments in the code, the person didn’t utilize the idea of writing more tests to describe the problem that’s at hand. Often times, I find that the test can do a much better job explaining what that particular function can and can’t do to know why it behaves the way that it does, where you don’t need to read the comments to understand it.
[0:10:13.8] DA: Yeah, that’s interesting, it kind of comes back to a similar point that we had when we were talking about like pending tasks. The test can be a form of documentation for that as well as for how things work or why things are the way they are.
[0:10:26.7] MN: Right. I think that if you are to be elaborate and very descriptive in your test and your code is clear enough and legible to read and understand what’s happening then you may not even need that comment after all and it may even confuse the person even more reading the comment and then looking at the function.
[0:10:51.2] DA: Especially if you have like a UAV styled framework where you can kind of have like nested context that build up to a spec that reads pretty well, like English. I remember when I learned Privy for the first time and started using PDD after working with testing mainly in Python first and it’s kind of revelation because naming and testing in Python is often an exercise in just making a really long string of snake case words. You know, having different kinds of massive context is really nice for documentation.
[0:11:32.4] MN: Yeah, I think Ruby does a really good job at being able to be expressive in the English – in the testing framework to make it read like the English language to understand what’s happening.
[0:11:43.6] DA: Yeah, which is a skill in itself to write the right kind of description.
[0:11:47.8] MN: One of the problems I do see with comments as well is that often times, in the event that the function was refactored or made clear by a refactor in the function itself, the comment doesn’t get updated and it’s just a stale comment that doesn’t really align with what the function is now doing and then that causes a lot more confusion.
[0:12:10.9] DA: Yeah, there’s that quote that I really like where a comment is the only kind of code that can lie to you.
[0:12:18.6] MN: That’s a good one.
[0:12:19.5] DA: Because if you look at code and a computer looks at that code, it’s going to ignore the comment and it’s going to do the thing that the code says it should do.
[0:12:27.7] MN: That’s awesome. That is a great quote.
[0:12:32.4] DA: The same thing is true for test descriptions as well. The body of the test is definitely relevant and if you can clearly and concisely understand that as a documentation then that’s good. I mean, there’s definitely cases where you look at the description for a test and it’s just been copy pasta’d.
Like from some other method or like from similar class or even in the same class three times and it just says something completely unhelpful.
[0:13:01.6] MN: Yeah, good old copy pasta. I always get burned with the copy pasta from time to time. Even I myself may want to copy paste some things with some changes but then I forget the body and then when I review it in a poll request, like “Oh no, the body’s the same, I have to change what it’s actually doing.” It could be really bad.
[0:13:22.7] DA: Yeah, the perils of a 10x developer. Just 10x copy pasta.
[0:13:26.5] MN: Yeah, copy pasta driven development boys, that’s what I’m doing here.
[0:13:31.1] DA: Yeah, CPDD.
[0:13:33.1] MN: Yeah, one of the comments that I may not be totally against is when someone has to use the important flag in CSS. I kind of want to know why you’re doing such a thing in the first place because I know the person who might have written that already feels shameful about it.
[0:13:56.9] DA: Like a defeat.
[0:13:59.5] MN: You got to defend yourself as to why that important was there. I mean, often times, if you’re using a CSS framework or whatever and you have, yeah. You got to override something and then it’s like, “Well what’s going on here? You got some explaining to do.”
[0:14:16.9] DA: Yeah, right? That’s pretty true.
[0:14:20.0] MN: I mean, if possible –
[0:14:21.0] DA: I can also like, for like yes, lint overrides too if you’re doing like a disable next line. Maybe just – what’s up? What’s going on with your life?
[0:14:31.9] MN: Why are you disabling the ES Lint across the entire file, I mean, I need to know these things, don’t do that.
[0:14:40.8] DA: That’s a whole other podcast but I like linting a lot and it makes me sad when you just see global disables on the file. Yeah, disable the line, tell me what is that, which line was the one that did the bad thing?
[0:14:53.9] MN: Yeah, exactly. Which one broke the camel’s back, which forced it to disable all of the lint?
[0:15:01.6] DA: Yeah, I guess like besides like test being documentation, the code itself can be good documentation and if you’re breaking it down into really small focus methods with good names then hopefully you know, your wonderful code can read close to English language as well.
[0:15:21.8] MN: Yeah, no. I definitely agree, that is a good method to avoid comments altogether just to write very descriptive function names or variable names so that the user or the developer can understand what’s going on.
[0:15:35.5] DA: Yeah, something I was working on today, we had all those comic logic in this method and we’re basically trying to take a set of filters to a database query and then apply it. There was so much logic and then we extracted it all out, ended up with two things. It was like “Okay, this is what I’m going to do when I’m going to apply the filters, I’m going to reset the patch nation to page one and I’m going to apply the filters.” It’s like, “This really is it, it’s two lines, great.”
[0:16:07.4] MN: Awesome, those are the good times, definitely the good times.
[0:16:10.9] DA: Yeah, I guess like, in some cases, you do need comments as documentation, although having them in cases where you might get away with documentation in the form of a test or in a form of a refactored method is a bit of a small – there’s some good firms of documentation like if you are using like documentation and written tool, that can be pretty awesome to have that kind of standardized documentation in your public API’s for example, in Swagger or GraphQL, that’s going to be a really useful reference for future people.
[0:16:52.9] MN: Right, because you have – using Swagger as an example, there will be people who are using API that didn’t build the API itself so people want to understand how to use it and I think like that, as a form of documentation can be very useful across the code base, or across the users who are going to use their API.
[0:17:14.0] DA: Yeah, definitely.
[0:17:15.8] MN: What are some other automatically created documentation that uses comments?
[0:17:20.3] DA: Yeah, Sphynx is pretty popular for Python, a lot of people use that to generate like read the dock style documentation for their projects. I mean, from the very start of my programming in Java Dock.
[0:17:36.1] MN: Yes, I completely forgot about that.
[0:17:38.5] DA: Yeah, you get a lot annotations, your favorite author, what you ate for lunch.
[0:17:46.0] MN: What inspired you to write this function.
[0:17:50.7] DA: Your hopes and dreams.
[0:17:52.9] MN: Exactly. Yeah, no. Java Docs is really cool because he’s IDE and it kind of – you can hover over that function and just gives you a pretty thing of all the stuff that it gives you for lunch. I just think that like – when it comes down to like – if the Java Dock had a comment where it’s like, “I’m sorry,” that’s when I feel bad. “All right don’t apologize to me.”
[0:18:18.4] DA: I love these side of your ideas, apologizing for the method signature or something.
[0:18:23.7] MN: Exactly.
[0:18:25.0] DA: Yeah, it always felt kind of cool too when you could like generate the documentation and it looked exactly the same as like the Java standard library documentation. I guess besides that, these are not really like living inside the comment and inside the code but are kind of a commendation on the code and super useful. I was just looking at a project that I had done like two years ago and I was like, “I think I hosted this on Roku, I wonder what the URL is?” Nope, not in the read me.
[0:18:59.1] MN: What read me?
[0:19:01.0] DA: Only Heroku knows.
[0:19:02.4] MN: Man, how many dino’s exist right now on Heroku that aren’t being used? One must wonder. All right, I’ve worked at a – I’ve seen an example of read me’s being used and react in every component lived in a folder and the folder structure was the component. It’s test and a read me that describes some of the things of what this component does.
[0:19:26.6] DA: That’s kind of cool.
[0:19:30.4] MN: Yeah, that’s like a really nice way of separating out the code from the comments and that way you can have it in a mark down file, all the descriptions of these functions, what it does without having many lines of code written in comments that makes the file very big.
[0:19:47.9] DA: Yeah. I guess with that, I feel like I would find it challenging to keep that fully up to date all the time. I would try to keep that pretty turf. Just like thinking about all of the different containers that I worked with today and I can see how it would get very confusing without some level of documentation about what the relation of all these things are together but for a refactor it would be challenging.
I guess there’s also like story book, we talked about that a couple of weeks ago and I find that to be a pretty good for documentation too that everyone can kind of look at, there’s some good plugins that will even auto generate some nice things about your proc types and how you wrote the code too, before the story that’s showing and you know, shows the actual component on the page in addition to all that too.
[0:20:38.8] MN: We’ve been talking about comments for some time and I’m curious, what kind of comments did you run in to? I’d love to hear what people have to say about these comments.
[0:20:47.7] DA: Yeah, what story is your code telling you?
[0:20:50.0] MN: Exactly.
[0:20:51.3] DA: Please tweet us.
[0:20:52.6] MN: Yeah, tweet us @radiofreerabbit. I love to hear it, I’ll probably share some through the week and we’ll definitely start a banter on who has the best comments in their code base which is not good. I think we both agree, both Dave and I agree, trying to use comments very sparingly only when necessary if you really need check to see if you have the appropriate test that would explain what this function is doing or be very descriptive about the functions that you’re writing so you don’t have to write comments.
Don’t program when you’re drunk and leave to do’s.
[0:21:29.3] DA: Right. If you do leave a comment to really elaborate on some really specific domain knowledge or something else that isn’t related, or captured then, that’s awesome, put that in there but just be weary of the comment that is not –
[0:21:50.7] MN: Yeah, I want to give a quick shout out to Stride. Stride has a meetup called NYC Tech Debates, they’ve had their first one recently and it was about established companies versus startups and hiring and how do these companies hire and what is the process, what does it look like, why people would be interested in joining a startup versus a company that’s been established for many, many years. It was pretty cool. I had the opportunity to meet some people out there at the meet up if you were there. Shout outs to you, I mean hopefully I will see all of you in the next meet up.
That will happen on April 17th and it’s going to talk about retaining women in technology and what are some of the best practices. We have the CTO of meetup.com and the CTO of the New York Times to talk about what are some of the strategies into retaining and having diverse development teams, including women and non-binary individuals. So, feel free to come on down. You could find out more information at nyctechdebates.com.
I believe their Twitter is @nyctechdebates. Feel free to hit them up and follow and hopefully we’ll see you there. The last one had a ton of people for networking at the very beginning and then there’s food.
[0:23:08.8] DA: I missed it but I definitely want to check out the next one. It sounds awesome.
[0:23:12.5] MN: Yeah, it was a really, really good time. The space was amazing. You could find more information on the website. There was pizza, you’ve got to have Lacroy and some water and that kind of stuff.
[0:23:22.6] DA: Of course, as long as it’s not coconut I’m there.
[0:23:26.0] MN: Exactly, no coconuts for us. Just guys at Lacroy got us pizza and the debate itself was really, really interesting because you get to see two different sides and two different strategies, right? Like you have a company that’s been established for many years versus a startup and what’s that like. Why would people be interested in one versus the other and then people going back and forth, those are really cool and I am looking forward to the next one.
Again, there will be more information on the next one on nyctechdebates.com. Feel free to check that out. Let’s keep the conversation going on Twitter. Follow us now at Radio Free Rabbit. Like what you hear? Give us a five start review, it helps developers just 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.
Links and Resources:
