PHP comments are notes in your code that help other developers understand what’s happening in the program. However, they don’t affect how the code runs. Essentially, these are explanations for a part of the PHP code.

There are three main types of comments in PHP, which are listed below:

  • Single-line Comments.
  • Multi-line Comments.
  • DocBlock Comments.

Let’s take each one in-depth.

Single-line or One-line Comment

The single-line comment in PHP starts with a double slash (//) or a hash (#). They can be used for only one line. So, you can write them like this example: // this line is commented by slash, and # this line also by hash.

The one-line comment can be used at the end of the code line after the semicolon or at the beginning of a PHP block, and that can be like the below code.

$correct = true; // Is That Correct ?
if( $correct ) {
   echo "this line is correct!";
}

Here is another example of a hash comment in PHP.

$is_that_correct = true;

Anyway. In the following section, you will learn how to write a multi-line comment in PHP.

PHP Multi-line Comments

The PHP multi-line comment usually starts with a slash and an asterisk /* and ends with an asterisk and a slash */. This format allows you to write notes that span multiple lines.

It’s particularly useful when you need to explain something in more detail or when you want to temporarily disable a big chunk of code without removing it. For example:

Here is an example

/*
This function is getting users from database
Parameter: id -> integer value
*/
function get_users(id) {
    $users = array();
    return $users;
}

/* Disable a block of code here */
/*
function get_users(){

}
*/

You can also use the multi-line comment in another comment type, which is DocBlock Comments. Let’s move on to the following part to understand how to use it.

DocBlock Comments of PHP

These are special multi-line comments that start with /** and end with */. They are used for detailed documentation that other tools can read to understand your code better.

Here is an example:

/** 
* Detailed explanation here 
* It helps others know what this part of the code does 
*/.

One of the most common uses of DocBlock Comments is PHPDoc, which contains more specific information parameters for the block of a function or any part inside your code.

The following parameters can be used inside:

  • @api to specify the public method that can be used as an API source.
  • @author to show who wrote this source code.
  • @category to specify the current group name for the source code block.
  • @copyright appears when you use any source code that has copyright.
  • @license refers to licenses such as MIT and so many others.
  • @link to specify a relation between the current block and another one on the internet by the link.
  • @param refers to the function arguments or class attributes.
  • @version is the release number for the block.
  • @since refers to the age of the code block.
  • @return is the data type that can be returned using the PHP function.

And so many other keys to define the source code description. You can see more from here.

Let’s see how to use that with an example.

  /**
  * @author Montasser Mossallem
  * @version 1.0.1
  * @param $id with integer data type
  * @return array with products.
  */
  
  function products() {
     return [];
  }

That’s all. Let’s summarize it.

Wrapping Up

PHP comments are a block of notes that describe a piece of code. It can be a single line or multiple lines. It helps people understand the code better.

Additionally, there are three main kinds of comments in PHP: single-line comments, multi-line comments, and DocBlock comments. Let’s take them in a few lines.

  • Single-line Comments are short notes that begin with // or # and only cover one line.
  • Multi-line Comments are used to provide a lengthy explanation that requires more than one line. They start with /* and end with */.
  • DocBlock Comments are special types of multi-line comments that start with /** and end with */. They are used to offer a lot of detail about the code.

Thank you for reading. Happy Coding!