New Metric: How well is source code commented?

[gossi]

Similarily to what ohloh does. It relates the number of comments to the number of code. The higher the percentage of comments, the better well commented a project is. Must be easy to calculate this statistic as phploc provides all the data.

[schmittjoh]

I think such a metric could be debated :) but it's not alone in that regard to be fair.

Personally, I believe code is best if it can be understood without a lot of comments. I would argue that if code needs a high amount of comments, it likely suffers from complexity, bad naming or another code smell and should better be refactored.

I'm happy to discuss this topic though if you have good examples or maybe research papers which support your point :)

[Anahkiasen]

The two aren't necessarily opposed : you can have clear and elegant block, but comments indicate type hints, details about variables, and no matter how elegant your code you can't beat one short description in the docblock.

[schmittjoh]

Obviously commenting is a very subjective topic. I agree a certain amount of comments is helpful.

However, commenting is always a means for something else. For example, you add a type-hinting comment so that you have autocompletion, or so that static checks can be performed. Or you might comment to make a complex algorithm more comprehensible.

I have a feeling that a formula like "lines of comments / (lines of code + comments)" is not very insightful (I've not tested it though). It might make sense to also relate it to complexity. I think we would need to do some empiric research to see what results such a formula produces for real-world projects.

[gossi]

I was more adressing towards API docs. So, more comments = more API docs = more suitable to use for external developers, because they have a good documentation just from code assist. That was my background about it.

[schmittjoh]

Kind of related: PHPDocumentor seems to have some validators for doc comments (@param, etc.). I haven't looked deeply into it yet, just adding it here for reference :)

[Anahkiasen]

But even if that was added, like all tools it can be deactivated no ? So you just have to disable it by default and people who want can just make it count in the score or something ? I'm not sure how ratings work but could that be a possibility ?

[schmittjoh]

Yeah sure, it would be configurable. I don't plan to add it to ratings, only to collect the issues that it finds.

[Anahkiasen]

Well actually my issue personally is now how well the code source is documented but finding errors in said documentation – arguments description that are out of date, return types that don't match etc. Those are errors PHPDoc is able to retrieve, but I currently have to do it manually in local. Would be great if Scrutinizer could raise those as issues.

[schmittjoh]

I guess you meant to say "(...) is not how well (...) but finding errors". If so, I agree and that was the idea behind my comment :)

[Anahkiasen]

Yes sorry typo :p

[gossi]

I just got an idea about this and would like to share it, what can be done with measuring code comments.

1. Doc correctness:
   As @Anahkiasen says, if you write code and comments and your IDE doesn't help you refactoring or forgets about comments, then the types between your comments and your code can become different, so this would be nice to have checked and put into the issues list for scrutinizer (or isn't it already - sorry I'm not always stay up-to-date)

2. Code structure metrics with phpdoc:
   I value this idea more important than the other one, because it was my original thought when filing this issue. Similar to code coverage it would be phpdoc coverage. So, phpunit measure how much code of your code in percentage is tested. Similar there can be a metric of how much structures are documented with phpdoc. So, this could look like the following:

Structure	Documented	Available	Percentage
Classes	25	50	50%
Interfaces	10	30	33%
Traits	5	20	25%
Methods	250	333	75%
Total	290	433	67%

Which gives another nice badge for readmes 😉

[oparoz]

I'd like to see this implemented as well. It seems that right now, we're being penalised when writing lots of comments as it makes methods longer and lowers the rating.