Function Documentation

WordPress Function Documentation Progress

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