Proper commenting

[Sxooter]

This is one of my pet peeves. Proper commenting isn't about commenting every single line or small group of lines. If you have a function that's small and well defined, put a simple set of comments at the top describing what it does in simple terms, like so:

function mt(){
// This function returns time in microseconds
  $tmp = split(" ",microtime());
  return $tmp[0]+$tmp[1];
}

That's all you need. Well written code should be self documenting.

If your function is large and does a lot, it's ok to put comments near the complex / inobvious parts. for instance:

function replace_first_str($break,$replace,$str){
// This function replaces the first occurance of $break with $replace, leaving the others alone.
  $tmp = split($break,$str);
  $str = $tmp[0].$replace;
// We're done with the $tmp[0] so we toss it away
  unset($tmp[0]);
// Note the concat operator, and use of implode to reinsert the original break text.
  $str.=implode($break,$tmp);
  return $str;
}

Large blocks of comments should be enclosed with / / like so:

/************************
Program: yabba dabba doo
Version: 1.0
Author: Sxooter

This is the header for our program
It has the program name, version numbers,
Authors, and other important info.
It's a good idea for the lines to not be overly
wide, as it gets hard to read comments that
run off the screen in some editors.
This section should explain the overall
functioning of the program without getting
into too much detail.
***************************/

Note that there's plenty of wiggle room, and everyone has their own style. It's just important to not spend your time explaining things like:

// This is the $i for loop:
for ($i=0;$i<5;$i++){

[Jedi_Legend]

I can code in PHP well enough (or so I think), but I never documented my code at all. Now I find myself working on old code and it's really hard to figure it out sometimes. Comments really are nice to have. 🙂

[dotwebbie]

When I saw that subject, I thought you were going to complain about to properly using block comments, line comments, and doc comments. heh.

But yes, I agree. Another habit I myself have is comment coding. That is stuff like:

for($i = 0; $i < 20; $i++)
{
      echo("Hi");
} //bye

or

#hello world!
//Loop it, loop it good!
for($i = 0; $i < 20; $i++)
{
      echo("Hi");
} //bye

😃

[Moonglobe]

Originally posted by Sxooter
This is one of my pet peeves.

ya? well one of MY pet peeves is people who comment their code! 😃

[drawmack]

The way I was taught to comment is that someone should be able to port you stuff to another language based on your comments alone.

The way I really comment is by commenting functions and varialbes but then letting the code document itself unless it get's tricky. List if I use a temp variable for differenet things in different places I'll throw in comments that say x is not blah.

[Jeb_]

I believe that your comments should say what your code does, not how it does it - unless a section of code is particularly obscure or you're releasing the script for newbie view. Comment the function or code block so that anybody who looks at it will know instantly what it does. They can work out how it does it by themselves.

I base this on the premis that if anybody is going to be looking at your code, you'll be fairly safe in assuming they'll have a decent knowledge of the language you're coding in.

[laserlight]

Well, sometimes it is good to outline the algorithm used, it may help in maintenance.

[Sxooter]

Originally posted by drawmack
The way I really comment is by commenting functions and varialbes but then letting the code document itself unless it get's tricky.

I've always tried to use variables that are self descriptive enough to be self commenting. Since long var names are harder to type, I tend to use longer names on more seldom used / less obvious variables, while using shorter names for more commonly used vars.

I figure the more the var is used the more obvious its purpose usually is.

[Sxooter]

Originally posted by Jeb.
I believe that your comments should say what your code does, not how it does it - unless a section of code is particularly obscure or you're releasing the script for newbie view. Comment the function or code block so that anybody who looks at it will know instantly what it does. They can work out how it does it by themselves.

I base this on the premis that if anybody is going to be looking at your code, you'll be fairly safe in assuming they'll have a decent knowledge of the language you're coding in.

$agree_with_jeb++; // <- self documenting variable

[Moonglobe]

Is it just me, or wouldn't PHP's interpretted nature mean that the parser's stripping out comments would hit performance a bit?

[Jeb_]

Good question, actually. I don't think there would be a performance hit, as PHP doesn't actually "strip" the comments out first. The language scanner simply runs through the PHP file, doing nothing when it hits the comment blocks (except incrementing line numbers and what not).

I'm not too sure about this, I might go and have a closer look at the source...just for geekly kicks 😃

[Sxooter]

While I'm sure there's SOME performance hit relating to comments, I'd be willing to bet it's less than the difference of say a 750 versus 800 MHz processor or of a single extra line of executed code etc...

[Moonglobe]

Originally posted by Sxooter
While I'm sure there's SOME performance hit relating to comments, I'd be willing to be it's less than the difference of say a 750 versus 800 MHz processor or of a single extra line of executed code etc...

that's what i thought too, just being picky 😃

[drawmack]

// is faster then / /

the reason for this is that // is ignore the rest of the line so the compiler can very quickly skip that section but with / / the entire comment needs to be scanned to find the end cause it could be anywhere.

Also it is faster if you only use whole line comments so the preprocessor can pick them up on an earlier itteration.

HOwever I don't think it would be that much of a hit cause your code needs to be parsed at some point.

[Merve]

This forum has made me want to completely change some of my first scripts...completely change! Well they'll still do the same thing, but I'm going indent them, comment then, switch to switch statements (pardon the lame pun), and use censoring in my user input scripts. Also I'm going to obviously use htmlentities() on everything because it's my second favourite function (my favourite is explode).

I belive that proper commenting is essential, not the comment every line kind of commenting, but maybe a comment a the top of a user-defined function so that you know what it does...or stuff like that.

[BuzzLY]

As a long-time drone of the consulting world, one thing I have learned besides good commenting is the "comment header" block at the top of almost all of my scripts (those that are implemented on client sites, anyway). This header usually includes the following information:

• Project name / number

• My name and email address

• A short log of the major changes to the file

• Time/Date document was created

• Other information (like company name, etc.)

This way, if they have questions, they can contact me (and by having the email address right on the page, they won't be as tempted to call me on the phone. I prefer email to keep a "paper" trail.

It takes a lot of discipline to keep the information in these comment blocks updated, but I think it's extremely important, and worth the extra time.