Should You Comment Your Code?
Most beginning software developers think it is a good idea to put lots of comments in their code. When I first started out in software development, I probably wrote 3 lines of comments for each line of real code. But, the problem with this approach is that comments aren't living and code is. One changes the other grows stale.
Instead, it is better to write clear expressive code that describes itself so well that it doesn't need comments.
In this video I talk about why I try to avoid using comments in my code and why I think you should too.
Full transcription below
John: Hey it’s John Sonmez from simpleprogrammer.com, and today I'm actually going to bring you something a little bit different. I'm going to mix in some technical content in here. I realized that in these videos, I'm not really providing very much technical content and mostly inspirational stuff. I'm mixing things up a little bit here and you’re going to see a little bit more technical content, and perhaps some tutorials and some interviews later on here. Let me know what you think, by the way, if you like this or not and what kind of stuff you’d like to see on this channel. I’ll try to do that for you.
Today, what I want to talk to you about is comments in your code. This is something that I feel pretty passionately about, and I think is an area that a lot of developers, especially beginning developers, are confused about and they don’t understand really how to apply comments to their code and when they should use them and when they shouldn’t.
Let me tell you my stance on here. It’s a little bit of an extreme stance, but I stand by this and I’ll give you some reasons why, which is I say that you should avoid using comments in your code as much as possible. Now, this might seem really weird. I know when I started out in software development I thought that good code was code that had lots of comments because it seemed like good code to me, because, hey, if there are a lot of comment, a comment on every single line explaining what that code did I could easily understand that code. Even if I didn’t understand the programming language, I could understand it by reading the comments.
This seemed like a good idea to me. I wrote a lot of code that was just full of comments, and I thought I was doing a great job. I was being very thorough. A lot of software developers, I think, have that same feeling. Hey, that’s okay. I felt that way too but here’s the thing. This is what I found out a little bit later on. As I found out that I could achieve the same effect of explaining what something does by making the names of my variables and the names of my functions and methods more descriptive and not putting comments.
Almost everywhere in my early code when I go back and look at it where I had a comment, I could replace that comment with a descriptive variable, name, or a method or function. In fact, in some place I could create a method or function and for no other purpose then creating a description and breaking my code up to make it easier to understand and digest. One of the important parts of writing a good code is writing code that’s highly readable, that’s easy for someone to understand.
Now, the reason why comments don’t do this effectively is because comments are dead. They’re not living. How many times have you gone through an old code base and you have looked at the comments there and you’ve had to ignore the comments because they’re just plain wrong, because someone updated the code. They updated the functionality of the system but they didn’t update the comments. This happens all the time and you get to this point where you start to be a cynic. You start to be skeptical of comments because they often lie to you, and they can mislead you and put you down the wrong path. What happens? You start to ignore those comments and those comments don’t make sense.
Now, developers don’t mean to do this, but the fact of the matter is that the code itself doesn’t lie. It’s what actually gets executed. The comments don’t have to be updated with the code. That’s the problem. There’s a big disconnect there.
The other part of this is that a lot of times beginning programmers will make comments that are descriptive that explain what the language does. If you’re going to add a comment to your code and there are some places where it does make sense to add comment, it should be something non-obvious that can’t be communicated by the variable, names, or the functions and the methods or the structure of the code itself. Something like a secret formula for calculating some kind of mathematical equation that it just would not make sense to try and spell out in the code itself, because it’s complicated. It’s not something that’s going to be easily digested. You could put in a comment. There are even a paragraph of comments that explains that this is someone steer your equation, and this is why we’re using this here.
Other places for this would be a comment that explains some kind of weird or strange thing that you’re doing. Now, obviously, you want to avoid that as much as possible. Let’s say that there’s some kind of weird bug or some kind of memory type of management thing that you need to do something strange in your code. You add a comment that explains why you’re doing this action there.
Really, when you look at a really good developer’s code, at least most good developers, you’ll find that there are not very many comments but you’ll find that it’s easy to read their code because their method names, their functions, their variable names, tell the story. They have the information that’s in the comment.
Let me give you a tip here before I wrap this up, which is if you’re in the habit of writing a lot of comments in your code, that’s good. It means you’re trying to be thorough. I'm not trying to offend you or is it that you’re doing a bad job, because it probably means that you’re a good programmer and you’re trying to do a good job but try this out for a change. Go through some of your code where you have a lot of comments. Replace the comments and see if you can replace them with a good variable name. If you could break up the code that’s beneath that comment in a way that makes it self-explanatory that makes it so that the code communicates that what’s in the comment.
If you do this, I think you’ll find that you’ll be able to write a better and more descriptive and you won’t have this problem of syncing up code with comments. They’ll just improve your ability to describe things in your code overall, which is a very, very important thing to learn as a software developer.
I hope this video has helped you. If you like these type of videos, if you’d like to see more of this type of things, first of all, let me know. Let me know what you’d like to see on this channel and subscribe. Subscribe to my channel and you’ll get an update. I post a video every week. Also, check out my blog at simpleprogrammer.com. You can check on my Pluralsight courses at pluralsight.com. I have 54 courses on a wide range of technologies. I just thank you for watching this video. I really like the comments and positive feedback I’ve gotten from doing these videos. You guys make it all worth it so thank you and I will talk to you again next week.