Commenting

So far we’ve only looked at how to write PHP code. But just as important as your code can be the comments you write to explain what your code does.

PHP supports 3 different ways of writing comments. The first 2 are borrowed from C. There’s the double forward-slash format:

//this is a comment

and the multi-line comment:

/*
This is a comment that can include many lines
*/

And lastly there’s the shell-style comment with the # sign:

#this is another comment for just one line

The way the single line comment works is that everything following the start of your comment until the next new-line will be commented out and ignored by the interpreter, but with one rather important exception: PHP ending tags.

So, for instance, the following code will break:

// ¬†echo ‘<?xml ?>’;

And it doesn’t matter whether that’s a pair of forward slashes or a pound sign. Personally, I always use the forward slashes since there’s no functional difference between them, and it’s what I’m used to.

But anyway, what’ll happen is that the ?> will be seen by the interpreter as an end of the PHP block. Anything after that will just get printed directly to the page. Without the comment, PHP would have seen that as part of a quoted string, and known not to treat it like an ending tag. But once you have the comment there, it won’t recognize the quotes around it. It’ll just be treated like a closing PHP tag.

In this case, the only solution, if you really need that line commented out, would be to use the multi-line style comment. However, you have the freedom with that comment type to comment just a section of a single line.

Basically, the way multi-line comments work is they tell the interpeter to ignore anything between a /* and a */. Once the interpreter enters a comment block of that type, the only thing it looks for is an ending mark for that comment. And if it finds it on the same line or a thousand lines down the page, it makes no difference as far as the interpreter is concerned.

So, rewriting that comment:

/* echo ‘<?xml ?>’; */

And that comment will work just fine.

It’s worth noting that the multi-line comment ignores PHP ending tags as well. So, something like this:

<?php /* ?>

<p>Here is some HTML</p>

<?php */ ?>

would be a way of commenting out a section of HTML so that it didn’t get sent to the page. Just remove the beginning and ending tags for the comments and the HTML fragment will re-appear.

Now, the pit-fall with this type of comment usually happens when you try to nest them by mistake. Suppose you need to comment out a large block of code, but somewhere in that code there’s already a multi-line comment block, for instance like this:

/*

… lots of PHP code

/*
The following function does something wonderful
*/
function doSomething() {
//… do something wonderful
}
… more PHP code

*/

In this case, the PHP interpreter would see the first comment-ending tag, and treat everything after it as regular PHP. But then it would hit the intended comment-ending tag, and throw a fatal parsing error, since ‘*/’ isn’t a recognized PHP expression.

So, just be careful when blocking out large sections of code this way. If you use an editing environment like mine, it’ll alert you to this sort of mistake.

Now that we’ve looked at comments, a good programming tip is to use them to explain in plain English what your script is doing at each step of the way, before you actually write your code. This way, so long as your logic makes sense, you can just write your code to do what you intend to do and be fairly confident that your functionality will work as intended. If there’s a mistake to track down, then knowing exactly what the code ought to be doing can be a huge help, rather than trying to make an informed guess based on contextual clues.

Another use for comments is in removing a line or lines of PHP that you don’t want to execute. This can be especially important when you’re debugging, and we’ll look more at that in a later video.

March 09 2010 08:51 pm | Basics and PHP Programming Basics and PHP tutorial scripts

Trackback URI | Comments RSS

Leave a Reply