PHP - Comments

Previous
Quiz
Next

A comment in any computer program (such as a PHP program) is a certain explanatory text that is ignored by the language compiler/interpreter. Its purpose is to help the user understand the logic used in the program algorithm.

Although placing comments in the code is not essential, it is a highly recommended practice. The comments also serve as program documentation. Comments are also useful when the code needs to be debugged and modified.

Types of Comments in PHP

There are two commenting formats in PHP −

PHP Single-line Comments

They are generally used for short explanations or notes relevant to the local code. PHP uses two notations for inserting a single-line comment in a program.

Single-line Comments Using "#"

A line in PHP code starting with the "#" symbol is treated as a single-line comment.

<?php
   # Single line comment starting with # symbol
   echo 'Hello World';
?>

Single-line Comments Using "//"

PHP also supports C style of single-line comments with "//" symbol. A line starting with double oblique symbol is treated as a comment.

<?php
   // Single line comment starting with // symbol
   echo 'Hello World';
?>

A comment that starts with the symbol "#" or "//" need not be closed. The effect of these symbols last till the end of the physical line.

In other words, the PHP parser will treat the next line as a PHP statement and not as a comment even if there is no closing comment marker.

PHP Multi-line Comments

Multi-line comments are generally used to provide pseudocode algorithms and more detailed explanations when necessary.

The multiline style of commenting is the same as in C. One or more lines embedded inside the "/*" and "*/" symbols are treated as a comment.

Example of Multi-line Comment in PHP

Here is the example of a multi-line comment.

<?php

   /* This is a multiline comment example
   program to add two numbers
   Variables used - $x for first number, 
   $y for second number */
   
   $x=10;
   $y=20;
   print "Total = ". $x+$y;
?>

Note that you can put even a single line inside the "/* .. */" symbols. However, if there is a "/*" symbol in the program, it must have a closing end-of comment marker "*/". If not, an error will be displayed as follows −

PHP Parse error:  Unterminated comment starting line 3 in /home/cg/root/65ded9eeb52fc/main.php on line 3

PHP DocBlock comment (for documentation)

A "DocBlock comment" is a type of code comment that usually starts with "/*" and uses asterisks () on each line to give detailed documentation about a particular code component like a function, class, or variable, which allows developers to easily understand its meaning and usage; it is commonly used with tools that generate API documentation automatically.

Below is the example of a DocBlock comment.

/**
 * This function adds two numbers.
 *
 * @param int $a First number
 * @param int $b Second number
 * @return int Sum of $a and $b
 */
function add($a, $b) {
    return $a + $b;
}

Useful Tips for Comments

Here are some useful tips for writing better comments in PHP −

  • Always write comments for others, not yourself because always assume that another developer will read your code.

  • You should use proper english and grammar by avoiding shorthand, typos or ambiguous words. Because well written comments improve readability.

  • Do not comment the obvious if the code is self-explanatory, comments are unnecessary.

  • You can also mark areas that need improvement or debugging.

  • You should keep comments above the code block they refer to.

  • Update comments whenever the code changes.

  • Suppose if a function has a complex logic so you should explain it in detail by using the Block Comments.

  • You should always use the DocBlocks for functions and classes.

Print Page
Previous
Next
Advertisements