How can we improve comments in the source code? Was: [doc] What should be improved in DRLVM Doxygen documentation?

[Alexei Fedotov <al...@gmail.com>]

Andrey, Tim,
Thanks for sharing your point.

> I hope, even source readers also will be happy with improved comments.

I see here a different trend for the discussion. To my understanding
improving quality of comments in source files is a different task from
completing API reference:

1. Good API comments answer the question "How can I use it?" Answering
the question "How it works" is excessive for API comments. For
example, API reference for long integer arithmetic is much easier to
read without referencing performance optimizations. Such type of
documentation targets code customers, who don't read source code, and
even a getter should be described for them.

2. The comments which describe algorithms and optimizations are a must
for understanding a source code if you want, for example, to perform
bug fixes. Such type of documentation targets code owners, who are
reading the code. Such comments should be aphoristic and complement
the code, not rephrase it.

3. If we take C/C++, interfaces are documented in header files, and
algorithms are documented in source files. This is accepted practice
in Java design to hide a private implementation behind a public
interface. Two types of documentation reside in different files.

Doxygen is suited for generating API reference. Doxygen warnings won't
help us with *.c and *.cpp files because we don't feed these files to
the tool.

I found a way to measure quality of in-source comments using CCCC tool
http://cccc.sourceforge.net. You can check results for DRLVM at
http://issues.apache.org/jira/secure/attachment/12345645/cccc.zip
(please, start from .cccc/cccc.html).

When a code with high complexity (= has high MVG) is poorly commented
(= has low COM) the ratio MVG/COM (M_C column) becomes big and is
highlighted with red.

Stefano,
Please, don't miss another colored table. :-) Do you know better tools
to estimate a source metrics to add to Melody?

With best regards,
Alexei Fedotov


On 11/24/06, Tim Ellison <t....@gmail.com> wrote:
> Andrey Yakushev wrote:
> > I'd like common Doxygen documentation bundle for all Harmony or at
> > least for all classlib and all DRLVM code. It suites for #1 and #3 use
> > cases, and I hope, even source readers also will be happy with
> > improved comments.
>
> Agreed.  Of course, we will never prevent people reading the source
> code! But if reading an API description it is often easier to read the
> javadoc / Doxygen document.
>
> Regards,
> Tim
>
> --
>
> Tim Ellison (t.p.ellison@gmail.com)
> IBM Java technology centre, UK.

Re: How can we improve comments in the source code? Was: [doc] What should be improved in DRLVM Doxygen documentation?

[Stefano Mazzocchi <st...@apache.org>]

Alexei Fedotov wrote:

> I found a way to measure quality of in-source comments using CCCC tool
> http://cccc.sourceforge.net. You can check results for DRLVM at
> http://issues.apache.org/jira/secure/attachment/12345645/cccc.zip
> (please, start from .cccc/cccc.html).
> 
> When a code with high complexity (= has high MVG) is poorly commented
> (= has low COM) the ratio MVG/COM (M_C column) becomes big and is
> highlighted with red.
> 
> Stefano,
> Please, don't miss another colored table. :-) 

you kidding? you know I'm a sucker for colored tables and charts ;-) I
was already downloading it :-)

> Do you know better tools to estimate a source metrics to add to Melody?

I have a whole set of static analysis tools to try out, cccc was already
on my list.

-- 
Stefano.