PHP Comments

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.

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!

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();
}

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!