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

E55e0ec3c00f834d78fbdddeaa36e308?&s=32&rating=pg&d=https%3a%2f%2fwww

schwern

about 7 years ago
 

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

D1588981e0248aaa0174906c99df180e?&s=32&rating=pg&d=https%3a%2f%2fwww

Andy Lester

about 7 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.

81912bc5ca02376f99a5ee44531dee27?&s=32&rating=pg&d=https%3a%2f%2fwww

nothingmuch

about 7 years ago
 

See also: this topic :)

629ba5fd1e4b41a8a19829efa0be9786?&s=32&rating=pg&d=https%3a%2f%2fwww

AndyArmstrong

about 7 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.

884124d0169f41668fb3f948b2ba8b0a?&s=32&rating=pg&d=https%3a%2f%2fwww

Adam Kennedy

about 7 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!

Ac0c0eab36df58cd3676c1f03f4d5185?&s=32&rating=pg&d=https%3a%2f%2fwww

Steffen Mueller

about 7 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.

9f68b603a93343463b949b2ab140fbe0?&s=32&rating=pg&d=https%3a%2f%2fwww

mpeters

about 7 years ago
 

+1!

51d4559d326e8515c726c64ce04acc06?&s=32&rating=pg&d=https%3a%2f%2fwww

Ask Bjørn Hansen

about 7 years ago
 

++

96b7249c2977d27b115bf1b70ca61dc1?&s=32&rating=pg&d=https%3a%2f%2fwww

Justin J

about 7 years ago
 

++

5fa5a4e5ffdf883a1fcb1840c915d485?&s=32&rating=pg&d=https%3a%2f%2fwww

eserte

about 7 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?

5fa5a4e5ffdf883a1fcb1840c915d485?&s=32&rating=pg&d=https%3a%2f%2fwww

eserte

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

629ba5fd1e4b41a8a19829efa0be9786?&s=32&rating=pg&d=https%3a%2f%2fwww

AndyArmstrong

about 7 years ago
 

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

5fa5a4e5ffdf883a1fcb1840c915d485?&s=32&rating=pg&d=https%3a%2f%2fwww

eserte

about 7 years ago
 

@eserte:

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

063ffe4b4061aa874f09216cfd60d8f2?&s=32&rating=pg&d=https%3a%2f%2fwww

Robin Luckey

about 7 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?

Cheers

81912bc5ca02376f99a5ee44531dee27?&s=32&rating=pg&d=https%3a%2f%2fwww

nothingmuch

about 7 years ago
 

nothingmuch nails it above. agree 100%.

Dcede248731711cbf9a60ab74522347b?&s=32&rating=pg&d=https%3a%2f%2fwww

bombguy

about 7 years ago
 

We've received a patch on labs.ohloh.net 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

063ffe4b4061aa874f09216cfd60d8f2?&s=32&rating=pg&d=https%3a%2f%2fwww

Robin Luckey

about 7 years ago
 

Thanks Robin and Steffan!

629ba5fd1e4b41a8a19829efa0be9786?&s=32&rating=pg&d=https%3a%2f%2fwww

AndyArmstrong

about 7 years ago
 

Post a Response