WordPress.org

Ready to get started?Download WordPress

Forums

Request/Bitch: commented WordPress Code (21 posts)

  1. adnam
    Member
    Posted 9 years ago #

    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

  2. Beel
    Member
    Posted 9 years ago #

    Have at it, as for me - don't need the bloat.

  3. NuclearMoose
    Member
    Posted 9 years ago #

    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! :)

  4. planetthoughtful
    Member
    Posted 9 years ago #

    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

  5. Anonymous
    Unregistered
    Posted 9 years ago #

    Hey, isnt this a free program! Be happy its there! Search!

  6. charle97
    Member
    Posted 9 years ago #

    if the developers start commenting code, then a new version of wp would never be released.

  7. NuclearMoose
    Member
    Posted 9 years ago #

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

  8. TechGnome
    Moderator
    Posted 9 years ago #

    "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

  9. NuclearMoose
    Member
    Posted 9 years ago #

    TG,
    Did you gnaw your way out of the cage AGAIN?

  10. TechGnome
    Moderator
    Posted 9 years ago #

    How else am I expected to get my daily requirements of iron?
    TG

  11. Beel
    Member
    Posted 9 years ago #

    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 ;-)

  12. planetthoughtful
    Member
    Posted 9 years ago #

    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

  13. NuclearMoose
    Member
    Posted 9 years ago #

    @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. :)

  14. adnam
    Member
    Posted 9 years ago #

    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?

  15. sunshine
    Member
    Posted 9 years ago #

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

  16. Anonymous
    Unregistered
    Posted 9 years ago #

    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.

  17. TechGnome
    Moderator
    Posted 9 years ago #

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

  18. Anonymous
    Unregistered
    Posted 9 years ago #

    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
    // for overview)
    // $settings is set in bibble.php
    //
    // author: someone@a-place-you-can-mail-them.com
    // wiki: http://another-squiffy-link.org/
    //

  19. Anonymous
    Unregistered
    Posted 9 years ago #

    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.

  20. sweavo
    Member
    Posted 9 years ago #

    here's the functions that echo / return thread
    http://wordpress.org/support/4/3263

  21. Anonymous
    Unregistered
    Posted 9 years ago #

    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.

Topic Closed

This topic has been closed to new replies.

About this Topic

Tags

No tags yet.