In our previous post, we looked at cases where  including comments in your code is a good thing. This time we will look at the cases where comments are a bad thing. The examples that we mention below, are bad, mainly because they are used as a compliment to code that can be cleaner.

The lesson that we all should learn from this section is, that we shouldn’t put effort into commenting code, when the comment can be avoided by writing cleaner code.

Mumbling

Mumbling comments happen when a comment is written without giving enough thought to what is being written. After reading a comment of this kind you haven’t gained any extra knowledge, leaving you no choice other than examining  the code to try and figure out what the comment means.

Redundant Comments

Comments should be written when it’s not possible to express something with code. If the code that you have written is clear about what it does, then writing a comment that says the same thing as the code, is redundant and unnecessary.

// this variable holds the account balance
decimal accountBalance;

Misleading Comments

Sometimes a comment can be misleading. Other times it can simply be a lie. This happens because the comment isn’t precise enough and can be misunderstood. Another way that this can happen is that the code changed after the comment was written, but the comment was never updated.

Mandated Comments

There can be cases when the guidelines of the project you’re working on require you to comment every single function and parameter or class member. This adds a lot of unnecessary text to you code, and can help cause confusion.

Journal Comments

Before source control systems were widely used, it was reasonable to include comments at the beginning of files that kept track of the changes that were being made. Now it’s easy to see the changes that have been made to source files through time, so this type of comment has become obsolete.

Noise Comments

Noise comments can be seen as a type of redundant comment. If a comment doesn’t give you any new information or insight, then it’s just noise, and should be removed.

Scary Noise

Scary noise is the child of misleading comments and noise. When you copy and paste comments for your code, but forget to edit them, you have just created scary code.

// The customer's name
string Name;
// The customer's address
string Address;
//The customer's balance
decimal Balance;
//The customer's name
string Email;

We will continue looking at examples of bad comments in our next post.