Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I've been asked to run some code metrics in order to assess the quality of the code. One of the metrics was vaguely specified as "comments".

I ran Sonar on my code, and while I got 10% on the "comments/loc ratio metric", I got 50% on the "documented API" metric (which gives you the number of methods/classes/instance variables with javadoc comments).

I will try to convince the manager and the client that the "documented API" metric is more relevant than the first in estimating the quality of the code, especially that the metrics' goal is to assess the maintanability of the project in case another team took it.

Do you have studies/opinions about which of these two metrics is more relevant to assess the quality and maintanability of the code? I could use them as persuation tools. Thank you

share|improve this question
3  
I'd say the better metric is useful comments but how useful a comment could be rather subjective, and very difficult to measure with a tool. Anything that can be measured with a tool can also be "gamed", so that programmers can get high scores on the test without producing anything of value. –  FrustratedWithFormsDesigner Jun 28 '11 at 17:16

1 Answer 1

up vote 3 down vote accepted

No formal studies, but some thoughts on this.

  • Metrics on code vs comments rarely tell you anything useful
  • Really great, simple to read code needs very little comments
  • Public APIs for 3rd party consumption should be well documented, even if the methods are fairly self explanatory

So I'd say - make sure the public API is covered and have a quick scan of the code to see if extra comments are applied appropriately (e.g. When there's a tricky piece of code or a weird business rule to be explained).

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.