How to Comment in PHP – Code Snippet

Wondering how to comment PHP code? Here’s a featured snippet from the article.

//This is a single line comment.
//This is yet another single line comment.
 
//echo "I will be commented out";

That’s single-line comments. Know about multi line comments as well by reading the complete article.

Relevant Content: PHP Comments

Comments are super important. A well commented code stands out from a code with insufficient comments. There are many reasons for it, one reason is to document the underlying logic so you and your team members won’t feel lost while reviewing the code. Other reasons could be including important notes, reminders, or warnings.

Comments are also ideal for debugging the code. You can comment out single lines as well as blocks of codes and they won’t be executed. This would exclude a part of your code that seems to be buggy or you just don’t want it to run for some reason.

Given the importance of comments, we’ll see how to comment out code in PHP. We have also included a bonus section to help you grab some fundamentals of documenting a function that could help you in the long run.

Option#1 – Single line Comment in PHP

Double slashes // quickly comment out a line or two in the code, thus called single line comments. The example includes some single-line comments.


//This is a single line comment.
//This is yet another single line comment.
 
//echo "I will be commented out";

However, commenting out hundreds or maybe thousands of lines this way is impractical, undoubtedly. Fortunately, we have multi-line comments to the rescue and that we see next.

Option#2 – Multi line Comments in PHP

Multi line comments are ideal to comment out large blocks of code as well as documenting the code. All you need to do is to wrap the code in the docblock as /*{code}*/.

/*
This is a multi-line code.
We often comment out code blocks this way.
A quicker way to comment out large blocks.
Helpful in debugging the code.
*/
 
/*
//This function prints message to the console.
function printMessage($message)
{
    echo $message;
}
*/

The example shows how convenient it is to comment out a big chunk of code using docblocks. But there are some caveats to PHP comment lines that could unintentionally cause the code to break. Let’s see some common mishaps that are possible with docblocks.

Important Caveats to Multi line Comments in PHP

#1 Comment out Unintended PHP Comment Block

Sometimes multi line PHP comments could include part of code that isn’t meant to be commented out. Consequently, it causes the code to break. One common scenario is shown in the example.

 
function printNames($employee_list)
{
    /*
    foreach($employee_list as $employee)
    {
        if(isset($employee["Name"]))
        {
            echo $employee["Name"]."\n";
        }
    }
}*/
 
printNames([["Name"=>"John","Age"=>25],["Name"=>"Andy","Age"=>35]]);
 
//OUTPUT: PHP Parse error:  Unclosed '{' on line 4

Do you see the problem? PHP error says it all, we have an unclosed bracket for the function. It turns out that the docblock comments out the enclosing bracket of the function. This mishap happens quite often when you comment out blocks of code.

#2 – Problem with Already Existing PHP Comment Block

Commenting out a block of code that already includes a docblock can be problematic. It is more apparent in the example.

 
/*
function addNums($n1,$n2)
{
    /*
Description : This functions takes two numeric arguments and return their sum
*/
    return $n1 + $n2;
}
*/

Try out the exact code at your end and you’ll see the docblock doesn’t comment out the entire function but misses out on the return statement. It is not hard to guess why this happens. The closing */ pairs up with the /* at the top and thus creates a code block.

This could be fixed by either using a double slash for the comment in the function or by simply removing the docblock around it.

Bonus: Documenting a Function

Beginners in coding usually feel it unnecessary to document functions or classes. This is not a recommended practice and could actually backfire if you’re working with a team or even on your own. That’s why it is always important to learn some standards for documenting your code.

PHP defines some documentation standards. However, we won’t cover everything here. For this section, we plan to teach you how to effectively document a function according to defined standards. You’ve already seen how to comment in PHP, we’ll use multi line comments here as well as documentation standards.


/*
* This function returns sum of two integers
* @param int $n1 first integer 
* @param int $n2 second integer
* @return int summation of $n1 and $n2
*/
function addNums($n1,$n2)
{
 
    return $n1 + $n2;
}

The comments on the top of the function describe it and include information about its parameters and the return type. The tags like @param and @return are all defined by the standards.

We have the @param tag followed by the data type, parameter name, and an optional description. Generally, it would look like @param datatype $parameter_name optional description

For the return type, we have a @return tag as, @return datatype optional description

It might seem daunting at first to comment like this but this would become your second nature by practicing. We hope by now you know how to comment in PHP. Stay tuned for more informative articles related to PHP.

Conclusion

Wrap Up

This article explores all about comments in PHP. The article features the two types of comments – single line and multi line. Besides, the last section discusses some important caveats about comment lines. Hope this article has been fun. Stay tuned for more at FuelingPHP.