Comments in PHP: Single Line, Multi-line
Comments in PHP or any other programming languages are statements that are used to explain any line of code. They make the program code more understandable.
Comments are not considered as a part of the program. They are used for reading purpose only. Therefore, comments are ignored by the PHP interpreter at the time of execution.
Comments help developers to understand the functionality of the code, especially when revisiting it after some time or working with others.
For example, suppose you were working on a PHP project two years ago. Now you want to work on that project again. It may be difficult for you to understand the code after a long time. But if you have written comments in your program, you can easily understand the functionality of the existing code.
Thus, by including comments in your code, you improve its readability and maintainability, making it easier for yourself and others to understand the program. As well, you have saved your time. Comments also let to newly developers to understand the code who have joined the project.
Types of Comments in PHP
PHP language supports C, C++, and Perl style (Unix shell style) comments. There are two types of comments in the PHP language. They are as:
- Single line comment
- Multiple line comment
Single Line Comment
A single line comment, also called one-line comment, is used to give a name to any section of the code, a brief explanation of the code, or to provide short remarks during programming. There are two ways by which you can write a single line comment in the PHP program.
1. You can write the comment by using a pair of double forward slash (//) either above the line of code or alongside it on the same line. This style is borrowed from C++ language. Comments written in this way are single-line comments, meaning they extend to the end of the line and are ignored by the PHP interpreter during execution.
Example 1:
<?php
// This is a single-line comment in PHP using double forward slash.
echo "Hello World!"; // Output a greeting.
?>In this example, <?php is the start tag and ?> closing tag in PHP. Within these tags, we have used the double forward slash (//) to write a single-line comment above the line of code and alongside the code.
2. Another way to write a single-line comment in PHP is by using hash (#). You can use it either above the line of code or alongside it on the same line. This style is borrowed from Unix shell scripting language. In Unix shell scripts, the hash symbol is used to introduce comments. Let’s take an example on it.
Example 2:
<?php
# This is a also single-line comment in PHP using hash.
echo "Hello World!"; # Output a greeting.
?>In this example, we have used the hash symbol to write comments that are ignored by the PHP interpreter, just like the double forward slashes (//). This style is another way to provide brief explanations or notes for specific lines of code.
Multi Line Comment
If you need to write the comment in more than one line or multiple lines, you can use multi-line comment. This type of comment is used to write a long detailed explanation, a small documentation about the program, or lengthy comments.
Multi-line comments are written between /* and */ pair of characters and are not executed by the PHP interpreter as a part of the program. This style is borrowed from C language. Let’s take an example based on the multi-line comment.
Example 3:
<?php
/*
* This is a multi-line comment.
* It can span multiple lines.
* Useful for detailed explanations.
*/
echo "PHP is great!";
?>In the above example, <?php is the starting tag and ?> is the closing tag. In the next line, we have written multi-line comment using /* and */, which is used to comment one or more lines in the PHP code. The character /* is used to begin multi-line comment and */ is used to end the multi-line comment.
Nested Comments in PHP
PHP does not support nested multiple line comments. Nested multi-line comments mean one comment inside another comment. PHP does not allow you to put opening /* and closing */ characters inside another opening /* and closing */ characters.
If you try to do so, the program will generate a parsing error because the comment will automatically end at the first occurrence of closing */ character. Look at the below example.
Example 4:
<?php
/* This is a multi-line comment, /* multi line comment ends here.
*/ It will generate an error because the PHP interpreter will not
be able to detect the last closing character of comment */.
?>In this example, we have placed one multi-line comment inside another multi-line comment, which is not possible in PHP language. It will give an error when the code will be executed by the PHP interpreter.
Comments to Ignore Code
You can use single line or multi line comments to prevent specific lines of code from being executed. You can use a single line comment to temporarily remove or disable a line of code from the program written in PHP whenever you needed. Look at the below example.
<?php
echo "This line will be executed.";
// The following line is commented out and will not be executed.
// echo "This line is ignored.";
# Another way to comment out code:
# echo "This line is also ignored.";
?>Similarly, you can use multi line comment to temporarily disable a large section of code without deleting them, which you do not want in your program for testing, debugging or for other some reasons. By commenting out the code, you can easily re-enable it later if needed.
Best Practices for Writing Comments
There are the following key points that you should follow to write comments about the code in PHP. They are as:
- Keep comments relevant and up-to-date. Regularly update comments to reflect code changes.
- Always try to accurately write comments about the code.
- Use comments to explain “Why” not “What”. Write the comment to explain the reason behind the complex logic.
- Do not do improperly commenting out code. It can cause syntax errors or unintended code execution.
- Excessive comments can make the program code harder to maintain and understand.
