Commenting on comments

This statement is on my Ohloh page for ClamTk:

"Across all Perl projects on Ohloh, 28% of all source code lines are comments. For ClamTk, this figure is only 14%.

This lack of comments puts ClamTk among the lowest one-third of all Perl projects on Ohloh."

Now when I first saw that, the figure was probably 8%. Ohloh has since shamed me into obsessively adding more. I'm somewhat embarrased about the low number of comments - especially after developing this for 6+ years - but the 28% figure stuns me. In a good way, of course. As an amateur, it's probably just my lack of experience and limited exposure to other code bases.

5 Comments

28% is too much. That's nearly a third of your code which is not actually code. If you need that many comments, maybe your code isn't as clear as it could be.

Does the 28% figure also include the POD? That would both make sense and make it quite meaningless IMHO.

I agree, ohloh's metrics harks of pointy-hair managers who count lines of code, or number of check-ins but not what is actually written in them. I don't want to know how many lines of comment a project written in a less verbose language like Java or C# would require (less verbose syntax == more verbose code) to satisfy such a ratio.

Like other people here, I'm also not a fan of excessive commenting. Like Martin Fowler says in the book Refactoring, often the need of a comment is indicative that the code is not clear or factored enough. So I think that Ohloh measurement is silly and should be ignored, because it's not indicative of the real world worth of your code.

Leave a comment

About dave_m

user-pic I'm an amateur Perl geek and the author of ClamTk, a GUI written in gtk2-perl.