Even though commenting your code can be seen as a good practice for most people, not every comment is actually useful, needed or informative in any way to whoever is going to read it. As a matter of fact, commenting your code could be not only a waste of time but also a distracting element within the code.

Here I’ll explain two types of comments that are very common but never recommended. On the examples, I’ll be using javascript and HTML, but it applies to any language.

Captain Obvious

This can be the most common and useless comment of all. Basically, it’s when you explicit say something that is already written in the code.

// This print a message
console.log("Message")

Another programmer would understand that the code is printing a message, there is no reason to write a comment and say that. The code already says that.

// This call a function with two parameters
setTimeout(typeWord, typeSpeed);

This is kind of the same as the previous one. A programmer would understand that that’s a function call with two parameters.

// This for prints every element
for (let index = 0; index < array.length; index++) {
    const element = array[index];
    console.log(element)
}

The person who is going to read your code will be a programmer as well, therefore, extra explicit instructions are meaningless.

Why avoid it? because it does not adds any value to the code itself. You don’t need to point out every if, for, print or line on your code. There are few cases where a comment can help another programmer to understand what you did, but this is not one of those cases.

Close indicators

Text editors and IDEs already mark when a function, if, for or sections ends, adding extra indications for this means that there is no indentation.

<!-- start of section -->
<section>
    <h1>Title</h1>
    <div class="container">

    </div>
    <!-- end of container -->
</section>
<!-- end of section -->

As you read before, indentation is the reason why this kind of comments needs to be avoided.

If you need to comment a fragment of your code, it means the code isn’t clean.


Photo by Markus Spiske on Unsplash