How to Use Single/Multiline Comments in your PHP Code

This article will quickly walk you through how to comment your PHP code with single and multi-line comments.

What is a Comment?

A comment in programming is one or more lines of text that aren’t interpreted as programming instructions. Instead, the computer skips the commented lines when executing your code, completely ignoring them.

Comments don’t have to conform to any valid syntax. They’re just text that you read, and the computer doesn’t.

Comments can span single or multiple lines.

Single Line Comments

Single line comments are any lines of PHP code which begin with a // (double forward slash) or a # (hash).

// This is a single line comment

echo "This is not a comment";

# This is a single line comment too

// Multiple single line comments
// Can appear immediately after each other

Multi Line Comments

Multi line comments are contained with in a /* (forward-slash asterisk) and a */ (asterisk forward-slash) pair:

/*
Multi line comments
can cover multiple lines
and each line doesn't need to be started with any special characters
*/

The lines contained within the multi-line comment don’t need to start with any special characters – everything within is considered a comment.

Commenting Conventions

Comments are frequently used to tell your fellow developers (or remind yourself) the purpose of PHP code – what’s in a file, or what a class or function does.

There are some conventions around this so that comments are consistent and everyone gets the information they need.

If these conventions are used properly, software such as PHPDoc can be used to read the comments in your code and automatically generate documentation for your project.

Commenting PHP Functions

PHP functions are often commented to include information about what the function is expected to do, what parameters it accepts, and what value it returns.

/**
* Multiplies two numbers
*
* @param integer     $number    A number
* @param integer     $number    The number to multiply the other number by
*
* @return integer
*/
public function getImageNodes($number, $multiplier)
{
    return $number * $multiplier;
}

Commenting PHP Classes

Classes should also be commented to explain their purpose and what kind of object they represent:

/**
* Short description for the class
*
* Long description for class if necessary
*
* @copyright  2020 LinuxScrew
* @license    https://opensource.org/licenses/MIT
* @version    0.01
* @link       https://LinuxScrew.com
* @since      Class available since Release 0.01
*/ 
class MyClass {
    // ...
}

Commenting PHP Files

Developers will often leave comments at the beginning of an entire PHP file describing things like the version of PHP it was written for, where it belongs and who it was written by:

/**
* Short description of file and contents
*
* Long description if necessary
*
* PHP version 8.0
*
* LICENSE: https://opensource.org/licenses/MIT
*
* @category   Category Name
* @package    Package Name
* @author     Author <[email protected]>
* @copyright  2015-2020 LinuxScrew
* @license    https://opensource.org/licenses/MIT
* @version    0.1
* @link       https://linuxscrew.com
*/

A Quick Note on HTML Comments

HTML comment tags are not interpreted by PHP.

So, the PHP code in the below code example will be executed even though it is contained within a HTML comment.

<!-- comment
    <?php echo 'Hello!'; ?>
-->

If you’re mixing PHP into HTML, this is worth being aware of – the content echo’d above will be included in the HTML document, which could be a problem if it contained sensitive information.