Title: Request/Bitch: commented WordPress Code Last modified: August 18, 2016 --- # Request/Bitch: commented WordPress Code * [adnam](https://wordpress.org/support/users/adnam/) * (@adnam) * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/) * Hello WordPress developers, maybe in the next version of WordPress we could have some commented code! Rather than stream-of-consciousness PHP, it would be nice to have some explanations of — say — what particular functions actually do etc etc. I suggest before you take this project any further, you take some time to go through the whole 20000 lines and write in lots of comments. Especially function descriptions: not even putting these in is just laziness. Example: ` function get_currentuserinfo() { // a bit like get_userdata(), on steroids` This comment is virtually useless to anyone who did not actually wrote the program in the first place. If you intend to produce open source software, make it something that people can easily develop. It’s a drag having to pick through absolutely everything to make small changes. Regards, Adam Viewing 5 replies - 16 through 20 (of 20 total) [←](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/?output_format=md) [1](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/?output_format=md) 2 * [TechGnome](https://wordpress.org/support/users/techgnome/) * (@techgnome) * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102311) * 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](http://us2.php.net/manual/en/faq.general.php): * > 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](http://mosquito.wordpress.org) ?) 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 (Conjunction Junction, what’s your function?). A lot like the way the [help system works on PHP.net](http://us2.php.net/manual/en/). 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. TG * Anonymous * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102327) * adnam’s point about comments improving readability is valid. if adnam’s right about cached bytecode, then it rather takes away the bloat argument. got any references adnam? I couldn’t confirm or deny your claim. sunshine’s point about static files is invalid. trenchteam’s attitude is part of what’s holding back commercial applications of free software. I think the wiki idea is a good one, but also think it’s crazy not to have a few lines at the head of each file declaring its place in the General Overall. The thing is that comments should be written by a person with a top-down view of the entire application, because that’s what allows the commenter to actually add information. Nobody’s suggesting $i++; // increase i by one. what we need is // xyzfile.php // // functions to output formatted posts. functions here retrieve // data from the wobzygog layer (see [http://www.i-cant-believe-you-actually-clicked-this.org](http://www.i-cant-believe-you-actually-clicked-this.org)// for overview) // $settings is set in bibble.php // // author: [someone@a-place-you-can-mail-them.com](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/someone@a-place-you-can-mail-them.com?output_format=md)// wiki: [http://another-squiffy-link.org/](http://another-squiffy-link.org/) // * Anonymous * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102328) * what a strange thing to say. What’s your rationale? Do you really believe it will stop development in its tracks? Judging by my brief usage of WP so far, I think the developers are smart enough to avoid getting bogged down by *that*. However the inconsistency between functions that return and functions that echo is a sure indicator of a need for more cohesion if WP’s going to continue to improve and not collapse under its own richness of features. THIS is bloat, not comments. * [sweavo](https://wordpress.org/support/users/sweavo/) * (@sweavo) * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102329) * here’s the functions that echo / return thread [http://wordpress.org/support/4/3263](http://wordpress.org/support/4/3263) * Anonymous * [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102343) * charle97, you do realize that it’s far easier to add features to and debug well commented code, right? That’s lesson #1 in introductory programming classes. It’s not just an opinion, it’s a fact. Viewing 5 replies - 16 through 20 (of 20 total) [←](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/?output_format=md) [1](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/?output_format=md) 2 The topic ‘Request/Bitch: commented WordPress Code’ is closed to new replies. * In: [Requests and Feedback](https://wordpress.org/support/forum/requests-and-feedback/) * 20 replies * 9 participants * Last reply from: Anonymous * Last activity: [21 years, 5 months ago](https://wordpress.org/support/topic/requestbitch-commented-wordpress-code/page/2/#post-102343) * Status: not resolved ## Topics ### Topics with no replies ### Non-support topics ### Resolved topics ### Unresolved topics ### All topics