search

scrutinizer-ci / scrutinizer

Legacy repository - archives past feature requests/bug reports
https://scrutinizer-ci.com/docs
140 stars 36 forks source link

New Metric: How well is source code commented? #56

Open gossi opened 11 years ago

gossi commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

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

Anahkiasen commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

Yes sorry typo :p

gossi commented 9 years ago

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 :wink:

oparoz commented 9 years ago

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.