2.4. Commenting Your Code

There are several ways to write comments in PHP, but only two are encouraged. For inline comments, you can use two forward slashes (//); for block comments, you can start with a forward slash followed by an asterisk (/*), then close with an asterisk followed by a forward slash (*/).

$foo = 'some value'; // This is an inline C++ comment

/*
 This is a block comment in C style. It allows the developer to
 go into more detail about the code.
 */
function bar() {
    return true;
}

2.4.1. Inline vs. Block Comments

There's not really a right or wrong way to comment code, but accepted practice is to use inline comments for quick descriptions, such as the purpose of a variable:

<?php
    $foo = time()+7*24*60*60; // One week from now
?>

A block-level comment is typically used when more detail is necessary. For example, this comment might be used to describe an entire section of code:

<?php
           /*
            * Determines the UNIX timestamp for one week from the current
            * timestamp. Value is stored in $one_week_from_now
            */
    $days = 7;
    $one_day = 24*60*60;
    $now = time();
    $one_week_from_now = $days*$one_day+$now;
?>

2.4.2. Other Comment Styles

PHP also supports shell-style comments, which are single line comments that start with a hash mark (#). These comments are derived from command-line interfaces known as shells, which are common on UNIX operating systems. A shell-style comment looks like this:

<?php
    echo 'This is some text.'; # This is a shell-style comment
?>

The use of shell-style comments is strongly discouraged because such comments don't conform to PEAR coding standards. Find more information on this topic at http://pear.php.net/manual/en/standards.comments.php.