Complete PHP Programming/Comments

From Wikibooks, the open-content textbooks collection

Jump to: navigation, search

Contents

[edit] One line comment options

  1. // Comments here on one line (no closer needed or possible) 

  2. # Comments here on one line (no closer needed or possible)
    • Trying to close the comments early (e.g., to add a valid echo afterward) will not work (the succeeding text will still be considered a comment by the parser). This will thus produce nothing: 
      // Some comments... // echo "some words";
    • However, this could be done with a multi-line comment. The following will print "some words": 
      /* Some comments... */ echo "some words";
    • There is still a purpose to using multiple sets of single line comments on the same line. One can comment out the whole block, but include comments at the end of the line so that the comments will still be present when uncommenting the beginning lines.
// print "hello"; // This will print "hello" to the user (if the line is uncommented)

  1.  /* (As mentioned above, a multi-line comment opener and closer can serve as a one-line comment if closer placed on the same line; see also multi-line comments below) */
    • The only purposes of going through this trouble of adding a closer may be:
      • if one expects to expand the comment into multiple lines later
      • If one wishes to add a functioning PHP statement after the comment on the same line (though this is probably not good practice since other developers may not notice the succeeding code.

[edit] One-line comment issues

  • One-line comments end by either:
  1. a newline (an actual newline, not the \n newline mark ) OR:
  2. a closing PHP tag of the ?> or %> variety
    • As discussed in a section within the Escaping from HTML page, if a one-line comment is closed by a closing PHP tag (of the ?> or, if enabled in ASP tags, the %> variety (but not the </script variety), the succeeding HTML (or other non-PHP code) will not be commented. The following will thus print out "2":
// echo "1"; ?> echo "2";
    • If a one-line comment is followed (before a newline or a different closing PHP tag) by a closing </script> tag, the succeeding content will be considered as part of the comment. The following therefore will not print anything:
<script language="php">// echo "1"; </script> echo "2";

In fact, the closing </script> tag will itself be ignored in such a situation, thus a succeeding PHP opening tag will cause a parse error:

<script language="php">// echo "1"; </script> echo "2";
<script language="php"> print "more code"; </script>
  • If using a HEREDOC with an unclosed set of quotation marks, you can add a comment at least (necessarily) one line after the closing HEREDOC:
//"

or possibly:

#"


[edit] Multi-line comments

  • Typical multiple-line comments are preceded by a "/*", followed by text (including potentially on the same line as the opener) and ended with "*/"(potentially immediately precede on the same line; it is not like a HEREDOC)
/* 
...
...
etc.
*/
  • One can also use the following "if" conditional (or a similar expression which will always evaluate to false)
if (0) {
	echo "This code will not show up in the output.";
}

[edit] Multi-line comment issues

  • An unfinished multi-line comment will result in an error, unless it is starting (not closing) within an already existing multi-line comment block (i.e., it is non-greedy but only operates first on a complete open and close set)
    • The following will result in an error: 
       /* test */ */
    • The following will not result in an error: 
       /* test /* */
  • Thus, these multi-line comments cannot be nested (the first block up to "ending first comments" will be commented out, but the following */ will not have any opening /*for it). The following will therefore cause an error:
/*
Starting first comments
/* 
Starting Nested comments
Ending nested comments
*/
Ending first comments
*/
  • One can quickly toggle multiple blocks at a time by combining the styles (though this may not work show as such correctly in a text editor)

Original text with nothing commented out (thus printing "block one block two":

<?php
//*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

After taking out a / on the first line, the first block is commented out, printing only "block two":

<?php
/*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

Since the single line // overrides the multi-line /* .. */ two blocks of code can be switched at the same time back and forth into or out of comment mode.

Original text (printing out only "block one")

<?php
//*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>

After taking out a / on the first line, the first block is commented out and the second block is uncommented, printing out only "block two":

<?php
/*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>
  • phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor uses multiline comments (albeit with the opening immediately followed by an additional asterisk "/**") and other standardized tags within the comment block to create its automatic documentation. See the website for additional instructions. For example:
<?php
/**
 * This is my new fancy code...
 * @author Dr. Who
 * @version 1.0
 */
?>

[edit] Issues with either single or multi-line comments

  • When using multi-line comments with the typical "/" as delimiters in a regular expression, it is possible there will be a conflict, as an asterisk at the end of the expression (along with the closing "/" delimiter) could create something which would be parsed as a closer of the comments, thus leaving the succeeding "*/" without an opener:
<?php

/*
$subject = "Hi Joe";
$matching = preg_match($subject, '/^Hi.*/');
*/

?>

To avoid the problem, one could:

  • Use other regular expression delimiters--delimiters which may be less frequently encountered (and thus also in need of escaping) in most circumstances anyhow (e.g., "@" besides for email matching may be less frequent than "/")
  • Use an "if" with an impossible conditional which can:

Avoid regular expression conflicts:

<?php

if (0) {
$subject = "Hi Joe";
$matching = preg_match($subject, '/^Hi.*/');
}

?>

and also avoid nesting problems:

<?php

if (0) {

if (0) {
print "Hi ";
}

print "Bob";
}

?>
    • One disadvantage of the "if" method, however, is that it will most likely not be recognized by text editors as far as code coloring (though this may be an advantage for debugging, if one wishes to see more clearly what is inside the commented out block while running tests on the code).

[edit] Priority between single or multi-line comments

  • // overrides /* .. */. See above.

[edit] References

  • php.net/manual/en/language.basic-syntax.comments.php
Retrieved from "http://en.wikibooks.org/wiki/Complete_PHP_Programming/Comments"