Forums : Suggestions for Ohloh 2.0

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.

gidyn almost 13 years ago

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.

gidyn almost 13 years ago

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.

rogerio over 12 years ago

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.

wslany over 12 years ago