PHP Comments

Commenting is an essential part of any programming language. Comments are plain text inserted within a script to demonstrate the purpose of the codes, author name, written date, modification date etc. It helps to documenting codes properly. Professional and experienced programmers always write comments inside their codes.

  • Everything you write inside the opening and closing tags are considered as a statement and PHP interpreter try to execute these except the comments.
  • PHP comments written in the codes are not visible in the output, as PHP interpreter ignores texts written in comments when generating HTML from PHP. That’s why, you can’t see comments in the HTML source.
  • As comment is not processed by the PHP interpreter and not sent to the browser, it doesn’t slow down the execution time.

Why comments are necessary?

  1. No matter how well you know your code today, it is natural that after 2 weeks or six months you’ll have no idea what the code does. Well commented script can help you remind everything.
  2. You write a script which is not commented well and forward it to another programmer in your team. It may become hard for the person to understand what the codes are for. A well commented code is a release.
  3. During testing, you’ll need to comment a portion of your code to detect bugs.
  4. To deactivate a portion of code temporarily for any reason.
  5. You may use comment as a reminder to add further code later.

PHP comment syntaxes

PHP support three comment syntaxes from three different languages.

  1. C++ style single line comment: This is a double slashes symbol (//). This is also a single line comment. Everything after this considers as comment till the end of the line or the PHP ending tag. Example- 
    <?php
 $length = 10; // $length contains default length
?>
  2. Shell script style single line comment: This is a Pound or number symbol (#).Everything after this symbol considers as comment till the end of the line or the PHP ending tag. 
    <?php
$salary = 3000; // $salary is the lowest salary.
?>
  3. C-style multi line comment: It begins with /* and end with */. Everything between these is considered as comment. As this commenting syntax can include a block of text, it is also called block comment. A good example of this comment could be the introductory text which includes detail of the script.
    Example:

    <?php
/*
First we catch the variable used in the form
Then, we’ll validate and sanitize the inputs.
At last we’ll insert into the database
*/
$Name = $_REQUEST[‘Name’];
...
…
?>

Where to write comments

  • Write single line comment or multi-line comment at the end of a valid PHP statement.
  • You can also write comments in a separate line.

(a) Don’t nest multi line comments into one another which is a common error. It will create error. As soon as PHP interpreter finds the */, it considers closing the comments where it is the inner comment.

<?php
/*
First we catch the variable used in the form
/* Then, we’ll validate and sanitize the inputs.*/
At last we’ll insert into the database
*/
?>
(b) In the single line comment everything after it may not be considered as comment if there is anything left after PHP ending tag. See the following-

// This is a comment. ?> This line is outside of the comment. It is a HTML text.

As the purpose of the comment is to document the code properly, so, any changes in your coding should reflect in the comment.

Recommended commenting syntaxes

For single line comment: Use double slashes (//) for single line/inline commenting. To write a short note, use this syntax. For example, to write purpose of a variable.

It is discouraged to use Perl/shell style hash (#) comment as a single line comment by the PEAR (PHP Extension and Application Repository) coding standard.

For multi-line comments: use /* */ to comment a block of code.