1. What Are PHP Comments?

PHP Comments are identical to comments in various other programming languages. A PHP comment is written as a piece of the program and only readable by developers. Further, the comments are not interpreted and, hence, remain unexecuted. They are generally overlooked by the interpreter or compiler and serves only the developers. This tutorial comprehensively elaborates on the structure, style, types, uses, and importance of comments.
There are a bunch of benefits to writing a comment in PHP code. Look at the example below to understand, what is a comment in PHP code?

A Comment in PHP Code

<?php
/**
* This file contains all the functions of the website
* Functions related to home page
* Functions related to Page
* Some functions related to Posts
* Functions related to Website Custom Post Types
* Also this file has hooks related to theme files
*
*
* @package Tuts Insider.Com
* @sub-package Tuts Insider
* @since 1.0.0
* @url https://www.tutsinsider.com
*/
?>

Tutorial Contents:

  1. Intro to PHP Comments, An Overview
  2. Similarity of PHP Comments With Other Languages
  3. What are the Types of PHP Comments?
  4. Importance And Uses of PHP Comments
  5. What Is A DocBlock And Its Uses?

2. Similarity With Other Languages

Since all programming languages support comments and they are an essential part of any programming language. Plus, every Programming language holds a basic style of comments.
As programming languages adopt practices from each other, therefore, the similarity of various code styles or comments is common. Hence, a PHP comment does have similarities with certain programming languages. Accordingly, a PHP comment has three distinct styles, which are borrowed from three different languages.

2.1. PHP Comments Like C++ Style

Because PHP has its origin in C++, therefore, it uses the comment style from C++. Commonly, PHP took single line comments // form C++ Programming language.

2.2. PHP Comments Like C Style

PHP uses a C Language behavior of block-level comment, also called a multi-line comment. The multi-line comments /* comment */ spreads from a single line to many lines for elaborating the code in every detail.

2.3. PHP comments Like PERL(Unix Shell Like)

Furthermore, PHP gained the comment style from the PERL programming language. These PERL style comments are single-line comments, just like the C++ style of comments. The only difference is the symbol # used for comments.

3. Types of PHP Comments With Examples

3.1. PHP Single Line Comment

PHP assumed this single line comment from C++ and PERL Programming language. Usually, there are two types of single-line comments as discussed above.

  • The first type of single-line comments starts with a double forward slash // and spans to end of the line
  • The second type of single-line comments starts with a Hash sign # and spans to the end of the line
  • Importantly, the single-line comment also terminates when whenever there is an ending delimiter ?> on the line
  • The delimiter ?> terminates the PHP code block
  • Further, if there is any HTML markup, it will be executed
  • Moreover, there are certain variations in single line comment as explained in the following examples

PHP Single Line Comment

Below is an example that elaborates on the syntax of a single line PHP comment.
[– The single line comment ends when a delimiter is encountered. After that, html is executed if any. — ]
<h3 class=”<?php // the_heading_class(); ?>“>Sinlge Line Comment With Double Slash</h3>
<h3 class=”<?php # the_heading_class(); ?>“>Single Line Comment With Hash</h3>

<?php
// This is a single line PHP comment.
?>
<?php
# This is another type of single line PHP comment.
?>

3.2. PHP Multi-Line Comment

The multi-line comments are alike to C++, CSS, and many other languages. A multi-line comment is also called a block-level comment. It has the following characteristics:

  • Firstly, multi-line comments start with a forward slash and a star /*
  • Secondly, multi-line comments end at a star and a forward slash */
  • Also, this multi-line comment spans from single to many lines just like HTML comments and CSS comments

PHP Multi Line Comment

Below is an instance that demonstrates the syntax of multi-line or block-level PHP comments. This block-level or multi-line comment spans to many lines or single line also.
<?php
/**
* The following functions are related to:
* 1- Front Page
* 2- Contact Page
* 3- Comments Section
* 4- Portfolio Section
*
* There is no function below that is related to:
* 1- Posts page
* 2- Archive Page
* 3-Custom Post Types Page
*
* @package Tuts Insider.Com
* @sub-package Tuts Insider
* @since 1.0.0
* @url https://www.tutsinsider.com
*/
?>

PHP Multi-Line Comments Error

Usually, PHP does not recognize the nesting of comments. Hence, if a multi-line comment is nested, it will be terminated to the first encountered start and hash */. Thus, comments nesting creates problems and sometimes may create a huge mess. Check the subsequent example for this.

Example

<?php
/*
This is a comment that spans to many lines.

/* This is a docblock for function */ (The first comment ends here.)

The comment is continued. (This portion of the first comment is left un-commented.)
*/
?>

4. Importance And Uses of PHP Comments

Normally, PHP comments are written as a part of the program. Each code block commences with a comment and many code blocks also contain comments within the code blocks. Additionally, there is no limit to write comments at any spot. The listing below confers the importance and uses of Comments:

  • Firstly, all the developers must adopt the habit of writing a comment in PHP code
  • Normally, comments are written by developers and for the developers
  • Also, a PHP comment makes PHP code more understandable
  • Furthermore, a PHP comment contains helpful information regarding the code after that particular comment
  • Also, it is a practice to write comments when a code is updated
  • PHP comments blocks are left everywhere in code as mnemonics and reminders
  • Importantly, these Comments support debugging by commenting out PHP code
  • Moreover, PHP multiline Comments are helpful when a developer shares his code with any other developer
  • Writing Comments make it considerably easier to understand the code for other developers
  • In the same manner, comments help a developer when he comes back to his code after a long time
  • Hence, after a long time, the code is promptly understood by the developer
  • A PHP multiline Comment is also useful in writing PHP code documentation and then generating it, as explained below

5. What Is A DocBlock?

A docblock is any explanation of the code, within the code blocks, by using PHP comments. This explanation of PHP code, inside the code blocks, is called inline documentation. Moreover, a PHP docblock is very valuable for developers, individuals, and organizations to generate the documentation of the PHP code by using some sort of software like a phpdocumenter. Further, let’s see which elements of PHP can be documented:

  • Functions
  • Constants
  • Classes
  • Interfaces
  • Traits
  • Class constants
  • Properties
  • Methods
  • Files
  • Include and Require Statements

A docblock resembles the following illustration. Here a docblock is shown for a PHP class and PHP function only.

PHP DocBlock Example

<?php
/**
* This is a docblock for class
*/
class Tuts
{
}
/**
* This is a docblock for function
*/
function myFunction()
{
}
Give Us Your Feedback
OR
If You Need Any Help!
Contact Us