Is writing comments a bad thing?

Question

I've been reading an article "summary of Clean Code".

One of the points mentioned is "One of the most common reasons for the comments is because the code is bad"

I learned years ago that writing comments is a good practice for collaboration and to make it clear for other people who work on the project to get an idea of what is happening in a class/function/code block, etc just by reading the comment. I always knew that it's thoughtful to do that within teams.

I would like to get a clarification about this.

Answer 1

I think both things might happen. You could have well justified comments or comments just trying to make understandable a messy code.

Even the cleanest code (a not "bad" one) could be benefited by some comments. Those are useful, among possibly many other things, to:

• Indicate sections of the code that complete main steps of the overall process
• Clarify why you are using certain value in a function call when it is not so intuitive
• Help new collaborators easily understand the structure of your code (e.g., with open source)
• Indicate technical specificities when certain procedure is performed in practice in diverse ways

Now, this does not contradict the sentence you cite. The sentence does not imply each time there is a comment it is because the code is bad. It just says that bad coding is a quite probable reason for the usage of comments, which I find somehow intuitive. It requires more/better-developed skills to make "good" codes than to make "bad" codes, so there is probably more people out there making "bad" codes and trying to fill the hole with comments than people making neat codes with strictly useful comments.

So to give an answer to your question, I don't think one can say writing comments is a bad thing per-se. To rely on comments to try and correct bad coding practices would be the bad thing.