Have at it, as for me – don’t need the bloat.
Check out the template tag info in the WordPress Wiki. Then, after you have done some simple research and have an informed opinion, you can post your comments. There are a large number of people who have contributed code to WordPress, and while nobody claims that there are not issues, this is the first time I’ve seen anybody suggest doubling the size of the archive by adding comments directly in the code.
If you weren’t so lazy and actually poked around a bit before spouting off, you’d know this.
Cheers! 🙂
Actually, while I agree that this post was somewhat out of line, I know I was also a little overwhelmed by WP’s structure and functionality when I first started looking into it. Thankfully, I’ve come a fairly long way in a few days, with the help of others in the forum and with reference to the Wiki.
One suggestion might be that at the top of each file a URL could be included pointing to the Wiki page(s) that give further information about the contents of that file.
That way we avoid the bloat, and we address the fact that the first place many newcomers are going to start wondering about what all the bits and pieces do is after they’ve opened one of the files in their text editor but before they’ve discovered the support forum and the Wiki through trial and error.
Just a thought.
Much warmth,
planetthoughtful
Anonymous
Hey, isnt this a free program! Be happy its there! Search!
if the developers start commenting code, then a new version of wp would never be released.
@planetthoughtful,
You make a very good point about using the Wiki, and, in fact, that is what is planned to be done. Would you like to help with it?
“Documentation? We don’t need no stinkin’ documentation.” “If it was hard to write, it should be hard to read.” — I forget where I picked those up from.
TG
TG,
Did you gnaw your way out of the cage AGAIN?
How else am I expected to get my daily requirements of iron?
TG
The actual lines around here are: “Documentation? We ain’t got no documentation! We don’t need no documentation! I don’t have to show you any steenkin’ documentation!” – gotta have the last line 😉
NuclearMoose,
If that’s a genuine offer, I’d genuinely like to say ‘yes, I’d love to help.’
Is there a list I would need to join?
Much warmth,
planetthoughtful
@planetthoughtful,
It is indeed a genuine offer. The documentation effort needs many hands.
There is a docs mailing list for WP which you can find here: http://wordpress.org/mailman/listinfo/docs_wordpress.org
Keep watching over your shoulder, because Podz might run you down as he is as busy on documentation right now as he is here supporting us users. 🙂
Thread Starter
adnam
(@adnam)
Commented code != bloat
PHP scripts are pre-compiled, so comments in the code only slow down their execution the first time they are run. If this really bothers you, you could strip all the comments from the code before going live with your site. As it is, I have never gained any meaningful increase in generation time by doing this.
Producing open-source software is a good excuse to comment your code, as people might want to re-use the code you write. I don’t want to waste time trawling the web for an explanation for a particular peice of code, when the function (as coded) has no english-language indication of what it does. I’m not “having at it” or “spouting off”; I’m pointing out a problem with WordPress.
What if I want to do more than adjust the templates of my site? For a start, I added the functionality of attaching uploaded files to particular posts in my WordPress site; it took considerably longer to program because the code is not commented. I don’t doubt the code is documented somewhere, and you can probably find out how to make common changes quickly, but if you want to go deeper it becomes quite frustrating … or maybe I’m just lazy?
“PHP scripts are pre-compiled, so comments in the code only slow down their execution the first time they are run.”
Uh, sorry but, that makes no sense whatsoever. WordPress doesn’t output static files (by default, there is a plugin somewhere, I think), so EVERY time is “first time”.
“I’m pointing out a problem with WordPress.”
Granted. (I do think some here are a little twitchy to smack down trolls, very protective of their favourite software. ) Just remember WordPress’ beginnings: this wasn’t written from scratch, it used to be “b2” or “cafelog”. As they’ve gone along, they’ve cleaned up code — they only just took away all references to “b2” in the filenames.
Anonymous
what sunshine said: it is not easy to document code you didn’t write and with an open-source effort with many contributors, lots just don’t bother and you can’t expect other people to make up their deficiencies. for example, the template tag page is incomplete because the people who write documentation are not the same people as code the functions in the first place. stuff gets missed out. while I agree it would be good practice for contributors to document their code fully, the feeling I get from these negative responses is that they are not willing to do so and that is their decision.
