Quakenet/#php Tutorial

Note: If you opened this page from an external URL pay attention that all chapters are linked together. Be sure you also read all prior chapters of this tutorial, otherwise you will miss relevant content explained before.

Comments

  1. What are comments?
  2. Syntax of comments
  3. Commenting out

1. What are comments?

Text or lines in your php scripts which are ignored by the php interpreter are called comments. This is like the html comments with <!-- -->. With these you can (as the name implies it) write comments inside your script. These are used to add e.g. the authors name or the license into the php script without interfering the php interpreter.

2. Syntax of comments

There are 4 types of comments in php but we only use 3 of them. And from them two are almost the same. These comment types are seperated into two groups, the one line comments and the multi line comments

  1. One line comments are comments which ends at the current line or at the ?>. These comments start with // (this is not the string escape sequence \\). The following text is marked as a comment and is ignored by the php interpreter.

    <?php
    echo 'Text'// echo a string

    // Generate a second text
    echo 'Another text';

    // echo "I'm not printed as I am inside a comment";

    echo 'I am printed, althought I got // in the string';

    // comment running until the php end ?><?php echo "I'm not in the comment anymore"?>

    As you see not every charactersequence of // is treated as a comment, e.g. if it is used inside a string.

  2. Multi line comments are comments which can be longer than one line. Instead of starting each line with a // a multi line comment starts with a single /* and stops with a */.

    <?php
    echo "Print something again";
    /* Some comments which
    use several
    lines
    until the ending */
    echo 'A normal php statement again';
    ?>

    For readability each comment can be written as you want, like indenting the lines.

    <?php
    echo "Print something again";
    /* Some comments which
       use several
       lines
       until the ending */
    echo 'A normal php statement again';
    ?>

    You can even exaggerate this to underline the comments.

    <?php
    /*************************
     * loading configuration *
     *************************/
    echo "config loaded";
    ?>

    For multi line comments you cannot use ?> to stop such a comment.

  3. The third type are comments for PHPDoc. These are almost identically to multi line comments but uses /** as the start of the comment. However it must be appended by a whitespace (typically a newline).

    <?php
    /**
    A comment in PHPDoc style
    */
    echo "normal php code";
    ?>

    You may ask why there are almost two identically comment tyes. PHPDoc are special comments which are used to document special parts of your php script. These are used before selfwritten functions.

    <?php
    /**
     * Output a number.
     *
     * The following function outpus the given number.
     *
     * @param i The number to print.
     */
    function output_number($i) {
        
    // ...
    }
    ?>

    The syntax of such PHPdocs is defined by the phpDocumentor project. It's much the same as the Javadoc Tool with the same idea. Special programms (this mentioned PHPDoc) read this comments and generate html files for documentation. This way other php programmers can easily read the documentation to understand what the mentioned function (or class) is doing.

3. Commenting out

Besides writing developer notes into comments you also can do stuff which is called commenting out. During the development sometimes you want to disable some part of the script but without deleting the code. You can do this by putting the php code inside a comment. Check the following example.

<?php
do_this
();
do_that();
and_this();
?>

If you dont want to call do_that() just put it inside a one line comment.

<?php
do_this
();
//do_that();
and_this();
?>

For more than one lines you still can use multi line comments.

<?php
do_this
();
/*
do_this();
and_this();
and_that();
and_now_this();
*/
and_again_that();
?>

There is a trick to active the commands in the comment again fast, instead of just deleting the /* and */. For this you must put the */ inside a one line comment with //.

<?php
do_this
();
/*
do_this();
and_this();
and_that();
and_now_this();
//*/
and_again_that();
?>

To reactive the execution of the statements replace the /* with a //*.

<?php
do_this
();
//*
do_this();
and_this();
and_that();
and_now_this();
//*/
and_again_that();
?>

Now you see the reason for the // before the */, otherwise you got invalid php code (and will get an parse error). Now you have 2 single one line comments. If you replace //* back to /* the statements are commented out again and you have one multi line comment.

As a multi line comment ends with */ its impossible to embed multi line comments inside multi line comments. This is not a problem as you normaly dont do this explicit. But it can happends if you comment out some code and some days later comment a wide area out.

<?php
do_this
();
do_that();
/*
deactivated();
deactivated2();
*/
and_this();
and_that();
?>

Now we want so deactivate the code from do_that() to and_this(). You can try this with a multi line comment.

<?php
do_this
();
/*
do_that();
/*
deactivated();
deactivated2();
*/
and_this();
*/
and_that();
?>

With this code php will stop the execution of the script. As you see in the syntax highlighting in this tutorial the outer comment isn't really an outer comment. For php the multi line comments start at line 3 and ends at line 8 (and not at line 10). In this case even the line and_this() gets executed. However, the whole script isn't run at all as the script results in a parse error in line 10.

Questions about the chapter

1. Which comment types exists?

There are 4 types, but we handled only 3 of them. These are one line comments, multi line comments and PHPDoc comments. The 4. type are one line comments which uses # as the start instead of //. A description about the comments in php can be found in the manual at Comments.

Back to Next to
Copyright © to the OPs of #php/QuakeNet Valid XHTML 1.0 Strict Valid CSS!