WordPress.org

Support

Support » Requests and Feedback » Request/Bitch: commented WordPress Code

Request/Bitch: 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 15 replies - 1 through 15 (of 20 total)
  • 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

    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?

    TechGnome

    @techgnome

    Moderator

    “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?

    TechGnome

    @techgnome

    Moderator

    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. 🙂

    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.

    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.

Viewing 15 replies - 1 through 15 (of 20 total)
  • The topic ‘Request/Bitch: commented WordPress Code’ is closed to new replies.
Skip to toolbar