For the moment I am reading Clean Code by Robert C. “Uncle Bob” Martin @unclebobmartin.
I just finished the chapter about comments that really made me think of something that I always argued about.
During my educating I argued that good code comment itself and thus the need for explanatory comments was redundant information. It was not always received in that way and the supervisor may also considered one as a bit lazy.
Today I feel that a comment must have a really good reason to be in the code. I have, in my profession, seen many cases where the comments deceives the reader of what the code is doing. This is dangerous and can cause much more damage than one can imagine. When you believe that the comment tells you what the code that you are calling will do. But instead it do it in a slightly different way. This may introduce hard to find bugs that can be really costly. It’s better to give the method a good name that explains what it is doing than writing a comment about it.
Another thing that comments seems to be doing are bloating the code and making it harder to read and follow. I have seen comments that are there just because the writer thinks that every thing must be explained with a comment. This will just bloat the code and making it much longer and harder to read.
One example of this is comments that explains what the core API methods of Java is doing. With modern IDEs it not needed and a good developer, in my humble opinion, should know the API and if its not known at the moment we have google to look it up today.
So write code that comment itself and omit the comments from the code!