Forums : Suggestions for Ohloh 2.0

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

schwern almost 8 years ago

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

Andy Lester almost 8 years ago

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.

nothingmuch almost 8 years ago

See also: this topic :)

AndyArmstrong almost 8 years ago

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.

Adam Kennedy almost 8 years ago

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!

Steffen Mueller almost 8 years ago

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.

mpeters almost 8 years ago


Ask Bjørn Hansen almost 8 years ago


Justin J almost 8 years ago


eserte almost 8 years ago

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?

eserte almost 8 years ago

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. :-)"

AndyArmstrong almost 8 years ago

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

eserte almost 8 years ago


A comment in a code line is counted as a code line. No half lines. If a line contains any code at all, the whole line is counted as code.

So yes, if you're the type of person who only writes comments at the ends of code lines (I'm seeing some assembly code in my mind right now), Ohloh will not count any of your comments.

This isn't perfect, I know ... ideas for improvement welcome.


Robin Luckey almost 8 years ago

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?


nothingmuch almost 8 years ago

nothingmuch nails it above. agree 100%.

bombguy almost 8 years ago

We've received a patch on to allow us to parse Perl POD strings as comments instead of code.

Many thanks to Steffen Mueller for putting this together.

We'll start recounting all of the perl code on Ohloh today, but I can't lie -- there's a lot of Perl in our system, and it might take a week or two to get through it all.

Thanks for your help!


Robin Luckey over 7 years ago

Thanks Robin and Steffan!

AndyArmstrong over 7 years ago

Post a Response