My projects, and Perl projects in gen...

My projects, and Perl projects in general, are being dinged because of "Few source code comments". It reports MakeMaker as only having 5%. Ohloh fails to take into account POD, Plain Old Documentation. Documentation embedded in the source code which often takes the place of comments and has a much higher quality.

A simple evaluation of the MakeMaker sources (*.PL, *.t and *.pm) shows that it's...

• 11549 lines of code
• 1180 lines of comments
• 9187 lines of POD
• 3623 blank lines
• 25539 total lines.
• 554 subroutines
• 45.22% code.
• 40.59% POD and comments

Please count POD for the purpose of calculating source code comments. It's very easy to spot in Perl code:

/^=\w+/ # beginning of a POD block

/^=cut\s*$/ # end of a POD block

Yeah, what he said. I've got lotsa Perl projects, most of them modules with embedded documentation.

A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team.

Ideally I would like that to also say "a low number of comments might indicate that the code is readable enough that it doesn't need them" ;-)...

Seriously though, every comment I write is a red flag for me. I don't like it when I'm doing something that isn't clear from the code itself, so if I catch myself trying to explain or make excuses I stop and think hard. Sometimes there's no way out, of course, but I think this counts for something too.

See also an interesting post on the subject by Aristotle Pagaltzis, which seems to share my sentiments in a more articulate manner.

In short, I've tried very hard to make my comment count low (no boilerplate, and fewer situations that need comments, I just have them when it's necessary or when I feel really witty), and I don't think that it merits a warning sign.

See also: this topic :)

I concur with my learned friends.

I'm fairly sure that the 150 odd modules in my repository have between them a good 50k lines of docs, but because Ohloh can't understand pod, like, say, sloccount, these don't appear.

I was shocked when ohloh told me the percentage of comments was below ten percent. And I thought I wrote rather too many comments than too little. Turns out I favour putting them in POD sections if they're longer.

So +1 from me!

Absolutely. Imagine how upset people would be if Ohloh didn't support JavaDoc or RDoc.

When I first came to the Krang project I thought it was amazing how much documentation it had. Then Ohloh says it's not very well documented. Definitely hurting projects that have their act together and not doing much to help Ohloh either.

When you do add support for POD make sure that you also look at documents with just the .pod extension. I know many projects that use that when they want to organize documentation that doesn't directly belong to a specific code piece.

+1!

++

++

Thinking about it again, it seems to me that Ohloh should distinguish code and comments and documentation. Comments != documentation. This would probably bring all the language averages down to 10% comment ratio or so. Also I wonder how a comment in a code line is counted. Half code line + half comment line?

From Robin on this thread (the one I linked to above):

We're going to open up our source code parser/line counter very soon. We're hoping some brave soul will take it upon themselves to add POD and docstring support to our parser. :-)"

.xs seems also to be missing. This should be categorized as C.

Well, why does the sum of comments + code + blank need to equal the number of newlines in the file? I think there is room for several dimensions: code vs. non code lines is one measure, commented vs. non commented lines is yet another, docs out of the total is yet a third. Then there's the issue of boilerplate... If i start all my files with a 30 line header saying "i edited this on date blah", and then including a verbatim license, and so on and so forth-- IMHO that doesn't count as comments, but actually meta data. I suppose that last one is very hard to fix perfectly, but maybe some sort of heuristic is in order (splitting up into block comments, and running heuristics on the text itself). And speaking of block comments - does a commented line with no text in it count as comments? or blanks?

Cheers

nothingmuch nails it above. agree 100%.

Thanks Robin and Steffan!