It is understood that the code metrics are intended to be general guidelines, are not always correct, and come with appropriate disclaimers. However, the commenting metric does not impart any useful information at all, is often counter-intuitive, and should be removed altogether.
I write comments when needed, usually when a method does more than one thing, or if the intent of some code is not self-evident. For projects following this not uncommon practice, "well-commented source code" means incohesive methods or obtuse coding, not "that the code is well-documented and organized".
Another form of "well-commented source code" is often written by beginners and managers:
//increment the variable i i++;
This coding style achieves 50% comment lines, none of which aid in comprehension, and all of which get in the way of reading the actual code.
This gets worse with XML source comments. Visual Studio likes to write multi-line templates such as:
/// <summary> /// Write something here. /// </summary>
As I don't have 52" monitors, I usually compress this to:
/// <summary>Write something here.</summary>
According to Ohloh, presenting the same information in a more compact form means that my code is 67% less well commented.
In summary, the percentage of lines which are comments is a generally meaningless measurement, and in many cases is a counter-indicator of code quality, contrary to how the factiods interpret it. "One line of comments per line of code" was said several decades ago by the company that brought us APL. Since then, the software engineering community has been moving in the direction of self-documenting code, while much more meaningful code quality metrics have been developed. Cohesion, coupling, cyclomatic complexity, and even lines of code per method may be beyond Ohloh's resources to compute (neither are they applicable to all supported languages), but this is no excuse for the classic PHB fallacy of preferring bad data over no data.
To put this in a different perspective, if I turn some well-structured code into spaghetti, then put in lots of comments to explain the now obtuse flow of control, Ohloh sees this as an improvement.
I agree, this metric is not useful.
Worse, as currently implemented it produces misleading results, due to the fact that it also counts source file headers as "documentation comments". In reality, in many (most?) cases these headers contain copyright notices, and/or a reference or even the full text of an open source license. So, for example, a ".java" source file may have a header with the MIT license, and absolutely no documentation comments at all for the Java code. Today, this counts as a "well commented" file!
My own OSS project, JMockit, is today reported as having a "very low number of source code comments". This is actually true on average, even though its public API is extensively documented; I don't see much value in internal implementation comments, however. My source files have headers, but they only contain two lines (which still shouldn't be counted). Other projects may get a "better" ranking on this metric simply because they happen to use larger headers.
So, at the very least, file headers for Java files should be excluded from the metric.
Note on "low number of source code comments": We have replaced almost all comments by clear, clean code and clear test code for the main code, following the guidelines and rationale provided by the books "Test-Driven Development By Example" (Kent Beck 2002) and "Clean Code" (Robert C. Martin 2008), along with other agile methods, thereby assuring a crystal clear and 100% up-to-date documentation, as well as enforcing a hard discipline strictly followed by us. This means that our code is actually very well documented and organized despite the factoids from Ohloh suggesting the contrary. Project Catrobat.
Copyright © 2013 Black Duck Software, Inc. and its contributors, Some Rights Reserved. Unless otherwise marked, this work is licensed under a Creative Commons Attribution 3.0 Unported License . Ohloh ® and the Ohloh logo are trademarks of Black Duck Software, Inc. in the United States and/or other jurisdictions. All other trademarks are the property of their respective holders.