[Discussion] Comments helpful or hurtful?

[smizzle]

One thing I've seen a lot of in as code and publicly available libraries is a LOT of comments. I've seen files with 3 to 4 times as much text in the comments as the code. I know a lot of this is put there to generate auto documentation, but when you're looking through the code and trying to get how it works, it makes it pretty hard to read in my opinion. Just wondering what other people think about it?

[Breen]

As with everything, too much is never good. Although, without any documentation, a lib would be even harder to understand.

Comments are there to provide users with verbose information, when they have a problem and should read the code. Normally, you never have to even open the source code of a given library. Only when running into a framework problem, should you go into the code.

Based on that fact, I think comments should be as verbose as possible, even if it hurts general readability. The comments are not there to make your code reading life harder, they are there to make the debuggers life easier.

[FizixMan]

http://www.ibm.com/developerworks/linux/library/l-clear-code/index.html?ca=drs-

[smizzle]

I think good documentation and usage example is ten times better than all the commenting in the world. Often comments explain abstract concepts or how it was implemented. The same can often be better shown through a few lines of code on how to use it.