Why Comments Are Bad

I recently read this book on Clean Code by Robert C Martin and there he talked about comments in our code which kind of got stuck in my head. So I decided to write a blog post to highlight some of the down sides of very frequently used comments in our code.

Comment

Comments are non-executing statements that we write in our code generally in order to explain the code intent or some other information.

Why Comments are bad

Most of the time we write comments because we do not write clean code. Every time we are in the position to write a comment, we should think it through. We should ask ourselves if there is a better way that we can write the code and demonstrate our intentions in the code itself. And every time we succumb to write comments in the code, we should feel guilty and failure that we couldn't write a self-explanatory code.

Let's take a look at an example:

foreach (var student in students)
        {
         //for late enrollment charge extra fee
         if (student.EnrollmentDate>new DateTime(2015,1, 1))
             enrollmentFee = enrollmentFee + 1000;
         } 

Here, the comment is written to specify the special logic for late enrolled students. Instead, it could have been written like this:

foreach(var student in students)
        {
                if (student.IsLateEnrolled())
                    enrollmentFee = enrollmentFee + 1000;
        }

Here, we just simply created a method with a name which we were writing in comments anyways as plain text. This is much more clear and easy to maintain as compared to a comment.

I know I am being a little harsh on comments but the main reason behind that is that the comments don't get updated. The older the comment, usually farther it is from its intention. It's very difficult to maintain comments. And bad comments are usually big lies and can be frustrating and are often big time-wasters. They make our code look ugly and cluttered. We should always be ready to put some time and effort to try to avoid comments, if possible.

Let's take a look at some of the bad comments in our code.

Bad Comments

Here, the property d is used to denote Start Date.

public DateTime d { get; set; } // Start Date

Instead, the variable could have been named liked this and then the comment won't be needed

public DateTime StartDate { get; set; }

Lying Comments

Everyone must have seen code similar to this.

//always returns true
        public bool IsAdmin()
        {
            return false;
        }

The comment must have been written a long time ago and since then the code has been updated but the comment hasn't. Imagine if the method definition is complex and comment is a lie, how frustrating can it be.

Noise Comment

These are some comments which are not needed. They are possible breeding grounds of turning into bad comments in future. 

public DateTime StartDate { get; set; } // Start Date

This comment should be removed to avoid unnecessary clutter.

Commented-out Code

Having commented code for possible later use should not be needed. We have very good source control systems these days and we should use their power in case we want to see the old code and revert back. We should not clutter our code base by having commented out code.

//public DateTime StartDate { get; set; } 

Useless Comments

This comment s not really telling me anything why this code is written like this.

public bool IsAdmin()
        {
            //shhhh don't tell this to anyone
            return (LastName == "Smith" || Role == "Admin")
        }

Conclusion

In this blog post, I showed a few places where we see bad comments which we can avoid and improve our code base. Having less cluttered and clean code increases productivity.
The intent of this post is to say that comments should not make up for bad code. We should be ready to apply little time and effort if we can to avoid such comments. However, sometimes comments are necessary and are good to have but those cases are rather few as compared to how liberally we use this feature. I am not saying that we should stop writing comments, I just want to say that we should use them more cautiously. Hope this post will motivate everyone to use comments more judiciously.

For future updates to my weekly blog, please subscribe to the blog