Comments & Bad Comments

You should always strive to write your code so that it does what it looks like it does.  Have you heard of the phenomenon called the “write-only code”? This is code that made some kind of sense to whoever wrote it at some point in time, but it is difficult to understand for anyone trying to read it a later date, even if the person reading is the author. This kind of problem can be resolved by comments in the code.

Although comments can be very useful but sometimes it can also go wrong. I saw a common mistake today, which is this:

//Updating all records

Sanitiser.Update(“All”);

//Updating 20 records

Sanitiser.Update(20);

As you can see, these comments are just repeating what the code already said. This is just a waste but surprisingly, this is very common. One of the reason for this is mainly because these developers have been told that comments are good, but they have no idea as to what makes a good comment. A comment should say something that is not obvious from the code and which is likely to be useful to anyone trying to understand the code.

Another common fault is this:

//Updating 30 records

Sanitiser.Update(50);

Here, the comment contradicts the code which is not very helpful. This kind of thing usually happens when someone modified/refactored the code without updating the comment. A quick review of the comments after a code change is always worth doing.

Leave a Reply

Your email address will not be published.