The Case Against the Comments

 At work, I have added javadoc comments on top of a public API. I have done this to make sure I understood the problem properly. It also helped the code reviewer to see why I have wrote the things I did. 

This however was not helpful to anybody. I have been reflecting on this for a while and wanted to list the things that backfired. 

No one Read Them

This was the first problem. I noticed that people were not really reading them and they did not had the effect I wanted them to have. It is also fair in my opinion. Why would you read them ? If you have stuff to do and if you have to do them fast, why would you read it through ?

We had to Maintain Them 

The javadoc comments had components which was linking some classes and if one was changing the method signature, they had to update the javadocs too. This is just creating more maintenance work for everyone else for something that is not mandatory.

They started to Lie

This is the main reason why comments had to go.  With refactoring, bug fixes or after development cycles, the original version of the comments were not the same as what the code was doing. Eventually they had nothing to do with the method they were documenting. 

Eventually I removed them because they were just cluttering the code and making it harder to read. 

During my bachelors degree, comments were important and during my first year working I was instructed to write them whenever I can. Though after several years and reading "Clean Code" I started to realize that the code should do the documentation and not the comments. 

So, in my opinion, writing a comment is like the emergency signal lights people use to park where ever they want. You can write them and think that it makes it ok but in reality you are only lying to yourself and you should not comment it in the first place.