Function Documentation

WordPress Function Documentation Progress

Ohloh No Longer Criticizes WordPress Comment Ratio

Ohloh no longer lists the comment to code ratio as a factor for WordPress! This will hopefully improve as the PHP code base continues to be documented. Hopefully, once the focus is moved over to automated testing, the bugs and functionality will be improved to the point where WordPress will be rock solid.

This will hopefully limit the overall criticism that other developers have on WordPress. It will be a long road for complete documentation and quality assurance in WordPress. It is both fun and worthwhile learning experience. It is something that should have been in WordPress since the early days, but that isn’t important.

What is important is that not only should the quality of the WordPress feature set and defects reduce but the overall quality and assurance of that quality should be improved.


January 12, 2008 Posted by | WordPress | , , , , | Leave a comment

WordPress Ohloh Comments Ratio Raises to 18%

The inclusions of comments into the core of WordPress has risen the ratio from around 12% to 18% and the goal should be to get that passed 26%, the minimal margin they have for most projects.

However, while the primary focus that I have is phpdoc style comments and documentation, it remains that writing other inline comments would move that percentage even higher. It seems that since the author of said code knows what it does, it is assumed that others can look at it and figure it out. That isn’t always the case with beginners.

I suppose my rule is that since I don’t understand JavaScript code that well, I write comments that is more explaining the what I’m doing to myself, more than explaining it to someone else. When I go back to the code, I want to know what it does, so that I don’t have to spend time figuring out my own code.

It could explain why inline documentation inside of functions is almost nonexistent. Granted, once the phpdoc style comments are finished, a grassroots effort could be made for writing inline comments for inside the functions. However, I rather think the codex does a better job of explaining matters.

January 6, 2008 Posted by | WordPress | , , , , | Leave a comment