PHP Comments

Learn how to write PHP comments, and how to comment your PHP code effectively, in this easy-to-follow PHP tutorial.

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!

Learn PHP With Ease!

Written by Matt Doyle — ELATED's resident Web programming expert — Beginning PHP 5.3 is a complete introduction to PHP, covering everything in these tutorials and lots more besides. Find out how to:

  • Set up PHP on your computer
  • Use strings, arrays, functions and objects
  • Create interactive Web forms
  • Handle cookies and sessions
  • Work with files on the server
  • Build database-driven sites with MySQL
  • Send emails from your scripts
  • Create images on the fly with PHP
  • Work with regular expressions
  • Write robust, secure PHP applications

...and lots more!

“What a pleasure it's been spending hours and hours studying PHP with this magical book.” — Lulio, Florida
“The book is not only great for learning, but I find myself using it constantly as a reference as well!” — David A. Stoltz

Buy Beginning PHP 5.3 now from Amazon.comBeginning PHP 5.3 or Amazon.co.ukBeginning PHP 5.3.

Follow Elated

Related articles

Responses to this article

There are no responses yet.

Post a response

Want to add a comment, or ask a question about this article? Post a response.

To post responses you need to be a member. Not a member yet? Signing up is free, easy and only takes a minute. Sign up now.

Top of Page