SitePoint Sponsor

User Tag List

Results 1 to 11 of 11
  1. #1
    SitePoint Evangelist
    Join Date
    Feb 2000
    Location
    England
    Posts
    568
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    commenting functions

    anyone got a link to a standard way to comment functions? starting a new app and would like to do it properly.

    a search for php coding style and function commenting revealed very little...

  2. #2
    SitePoint Wizard TWTCommish's Avatar
    Join Date
    Aug 1999
    Location
    Pittsburgh, PA, USA
    Posts
    3,910
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    However you want really. I usually do something simple like this:

    PHP Code:
    /* This function grabs the username from the database. */
      
    function getUserName() { etc... } 
    It all depends really. While commenting is good, it can be useless if you're 99% sure you'll be the only one handling your code. In times like that, it's not necessary to comment everything out there -- and yes, I'm aware many people say things to the contrary.

  3. #3
    SitePoint Evangelist
    Join Date
    Feb 2000
    Location
    England
    Posts
    568
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    am 99% sure other people will so sort of important.

    it is explaning what all the input variables and things like that that might be useful. I see so many functions and wonder what is going on and just having information about what the function is expecting helps.

  4. #4
    SitePoint Wizard TWTCommish's Avatar
    Join Date
    Aug 1999
    Location
    Pittsburgh, PA, USA
    Posts
    3,910
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Well, I don't think there's any kind of standard out there, but here's what I personally would recommend:
    • Describe each function right before it is declared: it's purpose, etc.
    • If you find it convienent to create variable with short or non-obvious names, include a comment to explain what they do.
    • I think you'd be best off assuming that anyone who's going to be messing around with the code will be fairly competent in terms of programming, so I'd skip commenting anything even remotely obvious.
    • You might want to use comments to denote the closing braces for any nested conditionals or loops.
    • If you're going to use a function with a function, the ternary operator, the modulus operator, or something else "specialized" that may not make sense to everyone, be sure to comment it.

    That's all that comes to mind: good luck!

  5. #5
    SitePoint Evangelist
    Join Date
    Feb 2000
    Location
    England
    Posts
    568
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    cool thanks.

  6. #6
    SitePoint Wizard silver trophy Karl's Avatar
    Join Date
    Jul 1999
    Location
    Derbyshire, UK
    Posts
    4,411
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Actually there is a coding standard for PHP as set out by the PEAR: http://php.net/manual/en/pear.standards.php
    Karl Austin :: Profile :: KDA Web Services Ltd.
    Business Web Hosting :: Managed Dedicated Hosting
    Call 0800 542 9764 today and ask how we can help your business grow.

  7. #7
    What's HTML?
    Join Date
    May 2001
    Location
    San Diego, CA
    Posts
    1,701
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    I'd have to disagree with Chris (as he expected I'm sure.) Even if you are the only one who will be reading or hacking up your code, commenting is important so that you remember what you were thinking at the time.

    I go back and look at some of my Perl code from 2 years ago and smack myself because I have no idea why I did something. If I had only wrote comments! I don't know about you guys, but I have better things to do then remember every little aspect about every script or program I've written.
    Ryan Kuhle - A Proud Advisor - Got Questions? Just Ask!
    Get your website started for less than $20! Click Here

  8. #8
    SitePoint Wizard TWTCommish's Avatar
    Join Date
    Aug 1999
    Location
    Pittsburgh, PA, USA
    Posts
    3,910
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Originally posted by RKuhle
    I'd have to disagree with Chris (as he expected I'm sure.) Even if you are the only one who will be reading or hacking up your code, commenting is important so that you remember what you were thinking at the time.

    I go back and look at some of my Perl code from 2 years ago and smack myself because I have no idea why I did something. If I had only wrote comments! I don't know about you guys, but I have better things to do then remember every little aspect about every script or program I've written.
    You are right -- I should have been more careful with my words. There are certainly some projects, though, that do not require commenting beyond a few basics here and there. I was simply trying to debunk the theory sometimes promoted that you should ALWAYS comment things thoroughly.

    You are right to disagree with me -- thanks for keeping me on my toes. I'll watch what I say next time.

  9. #9
    imagine no limitations exbabylon's Avatar
    Join Date
    Dec 2000
    Location
    Idaho, USA
    Posts
    452
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Always comments your code! And ALWAYS ALWAYS indent!!! I did not do that when I built www.LoadSwap.com, and I paid for it. It was my first program, I dreampt about it, ate and drank that program while I was designing it, however, I needed to go make some changes to it just four months after I had finished and launched it, and I was lost!

    So just a warning, indent and comment.
    Blamestorming: Sitting around in a group discussing why a deadline was missed or a project failed and who was responsible.

    Exbabylon- Professional Internet Services

  10. #10
    SitePoint Wizard TWTCommish's Avatar
    Join Date
    Aug 1999
    Location
    Pittsburgh, PA, USA
    Posts
    3,910
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Indent? Yes. Comment? Maybe.

    Don't comment for the sake of commenting. Don't comment because people tell you to. Comment because you are truly convinced it will save you time and/or trouble at some point. If you, after some careful consideration, don't think it will, it may not be worthwhile to go beyond minimal commenting.

  11. #11
    You talkin to me? Anarchos's Avatar
    Join Date
    Oct 2000
    Location
    Austin, TX
    Posts
    1,438
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    I agree with you Commish.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •