Code comments

January 09, 2014, 12:12:35 pm

Looking at the Ohloh page, there is this factoid:

Quotewith a low number of source code comments

following the link we discover that:

Quote from: https://www.ohloh.net/p/ElkArte/factoids#FactoidCommentsLow ElkArte is written mostly in PHP.

Across all PHP projects on Ohloh, 32% of all source code lines are comments. For ElkArte, this figure is only 20%.

This lack of comments puts ElkArte among the lowest one-third of all PHP projects on Ohloh.

A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team.

So, I'd say that one of the goals for 1.1 should be to reach at least a 25% of code comments.
I think it is not impossible... at least if I stop committing uncommented code.

Re: Code comments

Reply #1 – January 09, 2014, 12:53:40 pm

Quote from: emanuele – January 09, 2014, 12:12:35 pmLooking at the
I think it is not impossible... at least if I stop committing uncommented code.

LOL, but yes, that's a goal we can reach..

Re: Code comments

Reply #2 – January 09, 2014, 05:05:22 pm

Yeah! You know I love commented code

... it helps with my CRS syndrome. To note at some point that was below 19% so we have made some progress. Some areas just need general flow comments, others really need all the options listed (ie. createlist) and what they do.

Language	Code Lines	Comment Lines	Comment Ratio	Blank Lines	Total Lines
PHP	366,503	92,982	20.2%	66,114	525,599
CSS	50,436	5,084	9.2%	2,450	57,970
JS	38,070	13,508	26.2%	8,352	59,930

Re: Code comments

Reply #3 – January 09, 2014, 06:55:52 pm

Quote from: Spuds – January 09, 2014, 05:05:22 pmit helps with my CRS syndrome.

For that you can do what I do: search the code!

lol

Quote from: Spuds – January 09, 2014, 05:05:22 pmTo note at some point that was below 19% so we have made some progress. Some areas just need general flow comments, others really need all the options listed (ie. createlist) and what they do.

That one would require a hundred or so lines of header alone! LOL

Quote from: Spuds – January 09, 2014, 05:05:22 pm[...]

That means to reach 25% of comments we have to add ~30,000 lines of comments!! xD (Actually ~15k because Ohloh counts the site code as well that is basically a duplicate (slightly outdated, just updated) of the main repo, so probably even some less.)

Re: Code comments

Reply #4 – January 09, 2014, 10:29:55 pm

Quote from: emanuele – January 09, 2014, 06:55:52 pm
Quote from: Spuds – January 09, 2014, 05:05:22 pmit helps with my CRS syndrome.
For that you can do what I do: search the code! lol

Wait, what are we talking about again?

Quote from: emanuele – January 09, 2014, 06:55:52 pm
Quote from: Spuds – January 09, 2014, 05:05:22 pmTo note at some point that was below 19% so we have made some progress. Some areas just need general flow comments, others really need all the options listed (ie. createlist) and what they do.
That one would require a hundred or so lines of header alone! LOL

Yes, helps with the count in one easy function

Quote from: emanuele – January 09, 2014, 06:55:52 pm
Quote from: Spuds – January 09, 2014, 05:05:22 pm[...]
That means to reach 25% of comments we have to add ~30,000 lines of comments!! xD (Actually ~15k because Ohloh counts the site code as well that is basically a duplicate (slightly outdated, just updated) of the main repo, so probably even some less.)

Well we better get started then

Spuds is really liking the split quote function !

Re: Code comments

Reply #5 – January 09, 2014, 11:11:42 pm

I'll just PR a file that is nothing but 30K of comments.

Re: Code comments

Reply #6 – February 01, 2014, 09:09:24 am

QuoteFor ElkArte, this figure is only 21%.

3 weeks, +1%!

(Well, it may be that we were at 20.49 3 weeks ago and 20.51 today, but still it's a 1%!

Re: Code comments

Reply #7 – February 01, 2014, 09:17:09 am

Updating Spuds table:

Language	Code Lines	Comment Lines	Comment Ratio	Blank Lines	Total Lines
PHP	361,875	95,694	20.9%	66,453	524,022
CSS	53,512	5,871	9.9%	2,644	62,027
JS	36,594	12,238	25.1%	7,741	56,573

Less php lines probably because... dunno, something big has been removed? I don't remember... oh well, less lines == less bugz!
There are approx. 3000 lines of comments more than 3 weeks ago, good job!!

Apparently we lost 1300 lines of comments in javascript...that's slightly odd...

Re: Code comments

Reply #8 – February 01, 2014, 10:27:39 am

Maybe when you updated the site branch? I seem to recall you saying that was being counted in all of this?

Re: Code comments

Reply #9 – February 01, 2014, 11:10:47 am

Quote from: Spuds – February 01, 2014, 10:27:39 am I seem to recall you saying that was being counted in all of this?

yep, the site repo is currently part of the repo collection on Ohloh.. I'd personally remove it since it's almost identical with the normal elkarte repo.

Re: Code comments

Reply #10 – February 04, 2014, 04:55:18 pm

I added yesterday (or it was Sunday? Don't remember) a kind of "ignore" to ohloh for this repo to ignore anything into /community/. Looks like it is working.
But now the percentage is back to 20% again... lol