adnam said "PHP scripts are pre-compiled, so comments in the code only slow down their execution the first time they are run. "
I beg to differ. From the PHP FAQ:
PHP is an HTML-embedded scripting language.
I still have yet to find anything to suggest that PHP scripts get compiled in any fasion. I don't think they do.
To the best of my knowledge, the amount of comments do not impact the speed at which something runs, compiled or not. If they did, I'd be up sh!t creek with out a paddle and program everything all on one line and no comments. The only thing it does impact is size. The more comments, the larger the file is. But that's not material to the running of the file, just the amount of HD space you have on the web server.
sunshine - no one is trying to "smack down" anyone or anything. This is a part-time hobby of sorts by volunteers where time is prescious and the to-do list is long (have you seen the items in the bug tracker ?) So they can either get the changes and features we all want in the product, or they can stop and start commenting the code. Yes, I know that it would have been easier to do had it been done all along, but I also know how easy it is to want to just get something coded and out there so people can use it. It's cases like that when code documentation gets put by the wayside. Would I like to see more comments in the code as to what's going on in there? Sure, but I'm also aware of how fast things are changing lately, and I would like to see 1.3 released sometime this year. If that means the commenting has to be put off to the side, then so be it.
What I think would be even more bene (At least for me) is a document of some sort that lists all of the WP directories, each file and sub dirs in them, for each file, a brief explanatoion of the duties of the file, a list of the functions in it, and for each function, the syntax, the parameter options, and a description of the function of the function (<singing mode="off key">Conjunction Junction, what's your function?</singing>). A lot like the way the help system works on PHP.net. You can drill down through the modules, functions, etc.
Often I know what I'm looking for, but have no friggin idea where it's located.