commenting functions

[padders]

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

[TWTCommish]

However you want really. I usually do something simple like this:

/* 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.

[padders]

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.

[TWTCommish]

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!

[padders]

cool thanks.

[Karl]

Actually there is a coding standard for PHP as set out by the PEAR: http://php.net/manual/en/pear.standards.php

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

[TWTCommish]

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.

[exbabylon]

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.

[TWTCommish]

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.

[Anarchos]

I agree with you Commish.