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.
\nInstead, it is better to write clear expressive code that describes itself so well that it doesn’t need comments.
\nIn this video I talk about why I try to avoid using comments in my code and why I think you should too.<\/p>\n
[responsive_video]http:\/\/www.youtube.com\/watch?v=ErW6fEvulAc[\/responsive_video]
\n[blank_space height=’3em’]<\/p>\n
Full transcription below<\/p>\n
[spoiler]<\/p>\n
John<\/b>:\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Hey it\u2019s John Sonmez from simpleprogrammer.com, and today I’m actually going to bring you something a little bit different.\u00a0 I’m going to mix in some technical content in here.\u00a0 I realized that in these videos, I’m not really providing very much technical content and mostly inspirational stuff.\u00a0 I’m mixing things up a little bit here and you\u2019re going to see a little bit more technical content, and perhaps some tutorials and some interviews later on here.\u00a0 Let me know what you think, by the way, if you like this or not and what kind of stuff you\u2019d like to see on this channel.\u00a0 I\u2019ll try to do that for you.<\/p>\n
Today, what I want to talk to you about is comments in your code.\u00a0 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\u2019t understand really how to apply comments to their code and when they should use them and when they shouldn\u2019t.<\/p>\n
Let me tell you my stance on here.\u00a0 It\u2019s a little bit of an extreme stance, but I stand by this and I\u2019ll give you some reasons why, which is I say that you should avoid using comments in your code as much as possible.\u00a0 Now, this might seem really weird.\u00a0 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.\u00a0 Even if I didn\u2019t understand the programming language, I could understand it by reading the comments.<\/p>\n
This seemed like a good idea to me.\u00a0 I wrote a lot of code that was just full of comments, and I thought I was doing a great job.\u00a0 I was being very thorough.\u00a0 A lot of software developers, I think, have that same feeling.\u00a0 Hey, that\u2019s okay.\u00a0 I felt that way too but here\u2019s the thing.\u00a0 This is what I found out a little bit later on.\u00a0 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.<\/p>\n
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.\u00a0 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.\u00a0 One of the important parts of writing a good code is writing code that\u2019s highly readable, that\u2019s easy for someone to understand.<\/p>\n
Now, the reason why comments don\u2019t do this effectively is because comments are dead.\u00a0 They\u2019re not living.\u00a0 How many times have you gone through an old code base and you have looked at the comments there and you\u2019ve had to ignore the comments because they\u2019re just plain wrong, because someone updated the code.\u00a0 They updated the functionality of the system but they didn\u2019t update the comments.\u00a0 This happens all the time and you get to this point where you start to be a cynic.\u00a0 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.\u00a0 What happens?\u00a0 You start to ignore those comments and those comments don\u2019t make sense.<\/p>\n
Now, developers don\u2019t mean to do this, but the fact of the matter is that the code itself doesn\u2019t lie.\u00a0 It\u2019s what actually gets executed.\u00a0 The comments don\u2019t have to be updated with the code.\u00a0 That\u2019s the problem.\u00a0 There\u2019s a big disconnect there.<\/p>\n
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.\u00a0 If you\u2019re 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\u2019t be communicated by the variable, names, or the functions and the methods or the structure of the code itself.\u00a0 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\u2019s complicated.\u00a0 It\u2019s not something that\u2019s going to be easily digested.\u00a0 You could put in a comment.\u00a0 There are even a paragraph of comments that explains that this is someone steer your equation, and this is why we\u2019re using this here.<\/p>\n
Other places for this would be a comment that explains some kind of weird or strange thing that you\u2019re doing.\u00a0 Now, obviously, you want to avoid that as much as possible.\u00a0 Let\u2019s say that there\u2019s some kind of weird bug or some kind of memory type of management thing that you need to do something strange in your code.\u00a0 You add a comment that explains why you\u2019re doing this action there.<\/p>\n
Really, when you look at a really good developer\u2019s code, at least most good developers, you\u2019ll find that there are not very many comments but you\u2019ll find that it\u2019s easy to read their code because their method names, their functions, their variable names, tell the story.\u00a0 They have the information that\u2019s in the comment.<\/p>\n
Let me give you a tip here before I wrap this up, which is if you\u2019re in the habit of writing a lot of comments in your code, that\u2019s good.\u00a0 It means you\u2019re trying to be thorough.\u00a0 I’m not trying to offend you or is it that you\u2019re doing a bad job, because it probably means that you\u2019re a good programmer and you\u2019re trying to do a good job but try this out for a change.\u00a0 Go through some of your code where you have a lot of comments.\u00a0 Replace the comments and see if you can replace them with a good variable name.\u00a0 If you could break up the code that\u2019s beneath that comment in a way that makes it self-explanatory that makes it so that the code communicates that what\u2019s in the comment.<\/p>\n
If you do this, I think you\u2019ll find that you\u2019ll be able to write a better and more descriptive and you won\u2019t have this problem of syncing up code with comments.\u00a0 They\u2019ll just improve your ability to describe things in your code overall, which is a very, very important thing to learn as a software developer.<\/p>\n