Latest / DevQuestions with Tim Corey / 010 Are Code Comments Important? Are Comments Bad? Is Code Self-Documenting?

Transcript

010 Are Code Comments Important? Are Comments Bad? Is Code Self-Documenting? · DevQuestions with Tim Corey

• 0:00
  SPEAKER_00: Welcome to the Dev Questions Podcast with Tim Corey.
• 0:03
  SPEAKER_00: Join us each episode as we tackle the questions you are asking about a career in software development, understanding the industry, and new technology.
• 0:12
  SPEAKER_00: If you're just starting out or you want to grow stronger as a developer, this is the place to get your questions answered.
• 0:19
  SPEAKER_00: Now, here's your host, expert developer and online educator, Tim Corey.
• 0:26
  SPEAKER_01: Are code comments important?
• 0:29
  SPEAKER_01: Are they bad?
• 0:30
  SPEAKER_01: What is self-documenting code?
• 0:33
  SPEAKER_01: In this episode, we're going to work through all those questions and more as we explore how do we actually use these comments and do so in a way that's responsible.
• 0:44
  SPEAKER_01: So let's start off with what is self-documenting code?
• 0:48
  SPEAKER_01: We can start from there and then work through is it really a thing or not?
• 0:53
  SPEAKER_01: So, self-documenting code, the idea behind it is that your code is written in such a way that it reads like a book, so that you don't have to put comments.
• 1:05
  SPEAKER_01: For example, if you have a method called start engine, then you probably don't need to comment that to say this method starts the engine.
• 1:14
  SPEAKER_01: You see how it that works?
• 1:17
  SPEAKER_01: It's self-documenting.
• 1:19
  SPEAKER_01: It tells you exactly what it's going to do.
• 1:22
  SPEAKER_01: So if you have a tricky bit, you wrap that in a method and call that method by the name of whatever it is.
• 1:30
  SPEAKER_01: So that's kind of self-documentation in a nutshell.
• 1:32
  SPEAKER_01: There's a little bit more to it, but that's pretty much the core foundation of it.
• 1:37
  SPEAKER_01: So we come to self-documenting code and the idea that we should not have code comments, there's a few reasons why that might be true.
• 1:46
  SPEAKER_01: For example, if we say, you know what, no code comments, then we have to write self-documenting code.
• 1:55
  SPEAKER_01: It's just a defense mechanism.
• 1:57
  SPEAKER_01: We have to be able to understand our code, therefore, we're gonna do things like name our methods better.
• 2:03
  SPEAKER_01: Because if you have the fallback of, oh, I'll just document that, or I'll just put that in comments, then it's much easier to write a method called method one.
• 2:13
  SPEAKER_01: Because why not?
• 2:13
  SPEAKER_01: You got a comment that says this starts the engine of the vehicle.
• 2:17
  SPEAKER_01: But that's not really a good thing, right?
• 2:20
  SPEAKER_01: Also, it helps you make sure that you have followed SRP or single responsibility principle, that first principle and the solid principles.
• 2:31
  SPEAKER_01: Because if your method starts the engine of a car and it turns on the radio, well, then that method name doesn't explain it real well, does it?
• 2:42
  SPEAKER_01: So therefore, you're thinking, well, I have to document that because I know it says start the car, but what it really does is that's your problem.
• 2:52
  SPEAKER_01: If you have to say, well, what it really does is your method is probably doing more than one thing.
• 2:59
  SPEAKER_01: Therefore, you should think about SRP and get back to one thing per method.
• 3:07
  SPEAKER_01: And so now you have a method called start car and another method called turn on radio.
• 3:14
  SPEAKER_01: Now it's clear, and the fact that you don't have code comments encouraged you to go down that path.
• 3:22
  SPEAKER_01: So this makes reading your code easier, it makes your code hopefully less complex as well.
• 3:29
  SPEAKER_01: If you are used to methods that have 50, 100, 200 lines of code in one method, you could probably look at that and say, you know what, I have to have comments.
• 3:40
  SPEAKER_01: It's important because otherwise I wouldn't understand what this method does.
• 3:47
  SPEAKER_01: In that case, it sounds like your method is too complex.
• 3:52
  SPEAKER_01: So the drive towards self-documenting code or code that has no code comments will drive you to shrink down that method and break it apart into smaller methods.
• 4:08
  SPEAKER_01: Then maybe your overall method is uh start car, but in there you have fire spark plug and you have um inject fuel.
• 4:18
  SPEAKER_01: I'm not a car guy, so you can figure it out from there, I guess.
• 4:22
  SPEAKER_01: But those are the submethods under start car.
• 4:25
  SPEAKER_01: So even though that start car method might have been huge, it really now is just a what I call a quarterback method, the method that calls the play, that says, okay, here's what's gonna happen.
• 4:38
  SPEAKER_01: That's what it is now, and it's just saying, okay, you do this, and then you do this, and then you do that.
• 4:44
  SPEAKER_01: Now it's really easy to understand what's going on in that method.
• 4:50
  SPEAKER_01: We've made our code simpler, easier to maintain, and clearer.
• 4:56
  SPEAKER_01: So those are some of the reasons why code comments might not be necessary or might even be counterproductive.
• 5:05
  SPEAKER_01: But let's talk through the other side of it.
• 5:09
  SPEAKER_01: What are some reasons why you might want to have comments in your code?
• 5:14
  SPEAKER_01: Well, when you write start engine for your method name, that's very, very clear and it's understandable what is happening.
• 5:23
  SPEAKER_01: But it doesn't tell you why it is happening.
• 5:26
  SPEAKER_01: Why do you start the engine there?
• 5:28
  SPEAKER_01: Why are you doing this?
• 5:30
  SPEAKER_01: And that's where code comments can provide a bigger picture, a more of a picture inside the mind of the developer who wrote this code.
• 5:40
  SPEAKER_01: So code comments provide a larger context and a better overall view of the code of what's going on.
• 5:49
  SPEAKER_01: Code comments also make sure you don't have any assumptions.
• 5:54
  SPEAKER_01: So if you say, okay, this is what this is doing, let's say start car, a code comment can tell you, yes, but it's not actually turning on the radio or it, you know, whatever the assumption might be normally.
• 6:12
  SPEAKER_01: It's not putting it in drive.
• 6:13
  SPEAKER_01: How about that?
• 6:14
  SPEAKER_01: So it's not putting the car in drive, it's just starting the engine.
• 6:18
  SPEAKER_01: That's what a code comment can do for you, is it clarifies what's going on.
• 6:25
  SPEAKER_01: So there's a few reasons why code comments might be helpful.
• 6:30
  SPEAKER_01: Also, they can put your ideas into clearer wording, especially if you're going to use this for documentation.
• 6:39
  SPEAKER_01: One of the things that I like about the XML comments above methods, where right above a method you hit the triple slash and it creates this XML section that you can fill out with a title and a description and explain each parameter.
• 6:54
  SPEAKER_01: Well, when you do that, that allows you to not only show the developer who is using your code right now, it also allows you to show future developers when they're using your library because it explains in more detail.
• 7:10
  SPEAKER_01: If you looked at Microsoft's methods, you'll often see not just the name of the method, but if you have it in TeleSense, it will also show you below that a little paragraph or a couple sentences about what that does.
• 7:24
  SPEAKER_01: Those are code comments.
• 7:26
  SPEAKER_01: So there can be a larger explanation around that method.
• 7:31
  SPEAKER_01: So there are some benefits to code comments as well.
• 7:35
  SPEAKER_01: So where do I land on the no comments versus comment everything spectrum?
• 7:43
  SPEAKER_01: And like almost every software development uh issue or problem or discussion in the industry, I land more in the middle.
• 7:53
  SPEAKER_01: And that's I think the best place for almost every uh holy war in programming.
• 8:01
  SPEAKER_01: If you land somewhere in the middle, you can take the best of both and not just go extreme.
• 8:08
  SPEAKER_01: So in this case, I think that self-documenting code is a great standard to try to live up to.
• 8:17
  SPEAKER_01: I think it's a a great place to start.
• 8:20
  SPEAKER_01: You should have method names that that are clear.
• 8:23
  SPEAKER_01: You should make sure that your methods do one thing, not multiple.
• 8:28
  SPEAKER_01: You should make sure that those long blocks of code, you re-evaluate those to see how you can make those clearer and maybe break them apart into reusable pieces.
• 8:40
  SPEAKER_01: So those are all great things.
• 8:42
  SPEAKER_01: At the same time, there is some larger context to share in code comments.
• 8:49
  SPEAKER_01: So I do like the idea of those method triple slash XML comments.
• 8:55
  SPEAKER_01: I like those a lot because it does give you that larger picture, the the why or the when, even an example of how to use your method.
• 9:04
  SPEAKER_01: Things that code itself doesn't necessarily give.
• 9:08
  SPEAKER_01: Now, there is the case for unit tests being your documentation as well.
• 9:15
  SPEAKER_01: That unit tests can tell you the how to use something and maybe even the when to use something, but mostly the how.
• 9:25
  SPEAKER_01: But it still doesn't give you the whole picture.
• 9:27
  SPEAKER_01: And that's where those XML comments can really flash that out and give you a bigger view as to what's going on.
• 9:34
  SPEAKER_01: I don't think we should assume that the reader knows everything about our code.
• 9:39
  SPEAKER_01: At the same time, I don't think that writing comments throughout your code is necessarily a good thing.
• 9:46
  SPEAKER_01: In fact, most of the time I think it's a bad thing.
• 9:49
  SPEAKER_01: Because what happens is you write a comment and you you have the best of intentions.
• 9:54
  SPEAKER_01: You say this this block of code here is doing this.
• 9:57
  SPEAKER_01: I use I used to document every single block of code, not every line, but every block.
• 10:03
  SPEAKER_01: The problem is what if I come back later and change that block?
• 10:09
  SPEAKER_01: For example, if you have an if statement and it says if is alive equals true, and then you say uh celebrate, you're still alive.
• 10:21
  SPEAKER_01: Well, if I documented that and I said this method makes sure the user's alive before celebrating the fact that they're alive, great.
• 10:30
  SPEAKER_01: But what if I go back and say, oh, you know what?
• 10:33
  SPEAKER_01: We need to refactor that and change that to say because the is alive is actually flipped for whatever reason.
• 10:41
  SPEAKER_01: We have say is alive equals false, don't celebrate.
• 10:45
  SPEAKER_01: Or something weird like that.
• 10:47
  SPEAKER_01: I change the logic of the code.
• 10:49
  SPEAKER_01: Cool, except for the fact that I have to remember to also change the code comment.
• 10:57
  SPEAKER_01: If I don't, the comment says one thing, the code says something different.
• 11:03
  SPEAKER_01: Well, now if I'm reading through the code and I read the comments and go, okay, that's what that block of code does, and skip over it, I'm actually getting a bad picture of what's going on in the code.
• 11:18
  SPEAKER_01: So that's a danger.
• 11:20
  SPEAKER_01: Now you may say, well, I document my project separately, I have this whole documentation section.
• 11:28
  SPEAKER_01: Great, except for the fact that you've now moved your documentation farther away from your code.
• 11:36
  SPEAKER_01: And so it's harder to keep those two in sync because you're doing it manually.
• 11:43
  SPEAKER_01: And with anything else in software development, we try really hard not to do manual work.
• 11:49
  SPEAKER_01: We know that manual work leads to mistakes.
• 11:53
  SPEAKER_01: We're human, we make mistakes.
• 11:55
  SPEAKER_01: So I don't love that idea.
• 11:59
  SPEAKER_01: I like to keep it as close as possible, and that's why I like the XML comments because they're really close to the method.
• 12:06
  SPEAKER_01: They still are a comment, but they're close to the method.
• 12:09
  SPEAKER_01: They're explaining what the method does, not individual section, and you can pull those out into documentation.
• 12:16
  SPEAKER_01: For example, Swagger, which documents APIs, can pull your XML comments and use that as documentation inside the Swagger system.
• 12:26
  SPEAKER_01: So there's a lot of really cool benefits with those, and they're very, very close to the source code.
• 12:32
  SPEAKER_01: There's still the problem of the code may change when the comment doesn't, and you have to watch out for that.
• 12:40
  SPEAKER_01: But I think there's a balance there between that and doing nothing.
• 12:46
  SPEAKER_01: Because doing nothing doesn't provide you with enough context.
• 12:51
  SPEAKER_01: Full documentation in code comments is too much because there's too much moving pieces that have to change with your code, and there's too many places for failure.
• 13:02
  SPEAKER_01: But kind of that middle ground of let's do code comments just for a method and using that XML commenting system.
• 13:11
  SPEAKER_01: Now, there's one other exception that I sometimes employ, and that's when there's just a tricky bit of logic.
• 13:20
  SPEAKER_01: For example, what if you have a regular expression?
• 13:24
  SPEAKER_01: If you've ever seen a regular expression, they're quite complex and they're hard to read.
• 13:28
  SPEAKER_01: They're dense.
• 13:29
  SPEAKER_01: And there's not a way to make them less dense.
• 13:34
  SPEAKER_01: One way to get around the fact they're dense is to create a method and say, okay, this method name is uh check for valid email address.
• 13:44
  SPEAKER_01: And that's the regex expression, a regular expression, for checking it for a valid email address.
• 13:50
  SPEAKER_01: That's cool, except for the fact that there may be some tweaks in there.
• 13:56
  SPEAKER_01: For example, there's more context.
• 13:59
  SPEAKER_01: So what's a valid email address?
• 14:02
  SPEAKER_01: Is it only a dot com?
• 14:04
  SPEAKER_01: That's silly.
• 14:05
  SPEAKER_01: No.
• 14:05
  SPEAKER_01: But is it, you know, do we have to have a certain structure involved with it?
• 14:11
  SPEAKER_01: What is a valid email address and how you validate it?
• 14:14
  SPEAKER_01: And that's where a code comment probably comes into play.
• 14:18
  SPEAKER_01: Because you say, okay, here is how we are building this regex.
• 14:24
  SPEAKER_01: So that's one exception.
• 14:27
  SPEAKER_01: Another one would be link expressions.
• 14:29
  SPEAKER_01: When you're doing a link query, they can get quite complex.
• 14:33
  SPEAKER_01: And so being able to say, this is what this query is doing can be helpful.
• 14:39
  SPEAKER_01: But again, remember, you're adding one more point of failure.
• 14:44
  SPEAKER_01: So make sure that if you do that, that you always update your code comment whenever you change an expression.
• 14:51
  SPEAKER_01: And if you can, avoid it by rewriting your query in such a way that it's more readable.
• 14:56
  SPEAKER_01: Remember that code is meant to be read by humans.
• 15:01
  SPEAKER_01: Alright?
• 15:02
  SPEAKER_01: So that's where I land on this spectrum of no comments or comment everything.
• 15:08
  SPEAKER_01: It's more in the middle.
• 15:10
  SPEAKER_01: I love them to know where do you land?
• 15:12
  SPEAKER_01: What do you think is the appropriate amount of comments?
• 15:16
  SPEAKER_01: Also, don't forget that I love to hear your thoughts on what further topics you want to have answered in this dev question series.
• 15:26
  SPEAKER_01: I have the under the podcast link on my I am Timcorey.com page, I have a link to ask a question.
• 15:35
  SPEAKER_01: I'm compiling that list and you may see your question in the future based upon your feedback.
• 15:42
  SPEAKER_01: Okay?
• 15:42
  SPEAKER_01: So leave those comments.
• 15:44
  SPEAKER_01: I'd appreciate it.
• 15:45
  SPEAKER_01: Thanks for listening.
• 15:46
  SPEAKER_01: As always, I am Tim Corey.
• 15:49
  SPEAKER_00: Thank you for joining us for this episode of Def Questions.
• 15:52
  SPEAKER_00: Tim is committed to making it easier for you to become a developer.
• 15:55
  SPEAKER_00: If you would like to help make more content like this possible, please like, subscribe, rate, and share Deaf Questions.
• 16:03
  SPEAKER_00: You can also send your questions to questions at IamTimcorey.com.
• 16:08
  SPEAKER_00: Until next time, remember, you are too smart and your time too valuable to waste it making all the mistakes Tim did.
• 16:15
  SPEAKER_00: When you're ready to learn to think and code like a professional developer, head over to imtimcore.com and enroll in a course.