PHP comment

Like most languages, PHP lets you add comments to your code. Comments are chunks of text that are ignored when the code is run by the PHP engine, but which are useful to programmers who need to read the code.

In this article you learn how to create PHP comments, and look at some good commenting practices, including how to write and format comments effectively. You also find out how to use comments to "comment out" chunks of PHP code.

Creating a PHP comment

There are 2 basic types of PHP comments:

• A single-line comment . This is a short comment within a single line of code.
• A multi-line comment . This is a longer comment that can stretch over many lines.

Writing single-line comments

To write a single-line comment , place either // (2 slashes) or a # (hash) before the comment :

// Here's a single-line PHP
 comment
.

# Here's another single-line PHP
 comment
.

The first comment style tends to be more popular with PHP programmers, but both styles are perfectly valid.

You can write single-line comments on their own — as just shown — or you can place a comment at the end of a line of code:

$widgetsLeft--; // Sold another widget!

Everything from the comment symbol (// or # ) to the end of the line is treated as a comment by the PHP engine, and is ignored.

Writing multi-line comments

To write a multi-line comment , start the comment with /* (a slash followed by an asterisk) and end the comment with */ (an asterisk followed by a slash). Here's an example:

/*

  Here's a long PHP
 comment
 spread over

  many lines.



  You can format
 a multi-line comment


  any way you like.

*/

Be careful: You can't nest multi-line comments in PHP . The following code won't work:

/*

  Here's the start of the outer comment
.

  /* Here's the inner comment
. */

  Here's the end of the outer comment
.

*/

This mistake is easy to make when commenting out PHP code, as described in a moment.

Good PHP commenting practice

It's important to comment your PHP code. Code has a habit of making sense at the time you write it, then looking like a mess in 3 months' time! If you add comments at the time you write your code then you will find that your code is a lot more readable when you (or another developer) return to it later.

A comment should explain what a chunk of code does, or is intended to do. Here are some good examples:

if ( $widget->stockLeft == 0 ) $widget->delete(); // Remove the widget if it's sold out



// Show only recent articles

for ( $i=0; $i < count( $articles ); $i++ ) {  

  if ( time() - $articles[$i]->pubDate < (86400 * 7) ) $articles[$i]->displayTitle();

}

Don't make the mistake of being too literal with your comments, though. The following comments don't really help:

if ( $widget->stockLeft == 0 ) $widget->delete(); // Call the widget's delete() method if its stockLeft property is zero



// Loop through all articles and call $articles[$i]->displayTitle() if time() - $articles[$i]->pubDate < (86400 * 7)

for ( $i=0; $i < count( $articles ); $i++ ) {  

  if ( time() - $articles[$i]->pubDate < (86400 * 7) ) $articles[$i]->displayTitle();

}

A good trick is to write your comments before you write your code. This forces you to think about what the code is supposed to do, rather than getting bogged down in implementation details.

Formatting comments

It's good to format your comments to make them easy to read. The following PHP comments are hard to read due to bad formatting:

// Retrieve all widgets

$widgets = Widget::getAll();

/*Update all the widgets in the database,

  changing each widget's quantity*/

for ( $i=0; $i < count( $widgets ); $i++ ) {  

  $widgets[$i]->quantity += $widgets[$i]->getNewStock(); //Set the quantity

  $widgets[$i]->update(); //Update the widget

}

These comments, on the other hand, are much easier on the eye:

// Retrieve all widgets

$widgets = Widget::getAll();



/*

  Update all the widgets in the database,

  changing each widget's quantity

*/



for ( $i=0; $i < count( $widgets ); $i++ ) {  

  $widgets[$i]->quantity += $widgets[$i]->getNewStock();   // Set the quantity

  $widgets[$i]->update();                                  // Update the widget

}

Commenting out PHP code

You can use PHP comments to "comment out" (temporarily disable) chunks of code. This can be useful when debugging your PHP scripts:

/*

if ( $widget->stockLeft == 0 ) $widget->delete(); // Remove the widget if it's sold out



// Show only recent articles

for ( $i=0; $i < count( $articles ); $i++ ) {  

  if ( time() - $articles[$i]->pubDate < (86400 * 7) ) $articles[$i]->displayTitle();

}

*/

However, be careful when commenting out PHP code containing multi-line comments. Since you can't nest multi-line comments in PHP , the following won't work:

/*

/*

  Update all the widgets in the database,

  changing each widget's quantity

*/



for ( $i=0; $i < count( $widgets ); $i++ ) {

  $widgets[$i]->quantity += $widgets[$i]->getNewStock();   // Set the quantity

  $widgets[$i]->update();                                  // Update the widget

}

*/

In this article you've learned how to write PHP comments — both single-line and multi-line — and looked at some useful commenting techniques, including how to write meaningful comments, how to format comments, and how to "comment out" pieces of PHP code. Happy coding!