PHP Comments - Types, Importance, And Uses

1. What Are PHP Comments?

This tutorial relates and explains PHP Comments, which are almost identical to a comment in any other programming language, although there might be a slight difference. Basically, a PHP comment is written as a piece of the program and only readable by developers or documentation generators. Further, the comments are not interpreted and, hence, remain unexecuted. They are generally overlooked by the interpreter or compiler and serve only the developers. This tutorial comprehensively elaborates on the structure, style, types, uses, and importance of PHP programming 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.

<?php
/**
* This file contains all the functions of the website
* Functions related to the 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
*/
.
.
?>

2. Similarity With Other Languages

• Just like the comments in PHP code, all the programming languages support and includes the comments, and they have their own uses and importance in any scripting language.
• Also, every Programming language holds a basic style and syntax for incorporating the comments inside the code as we will see the usage of PHP comments in this tutorial.
• Moreover, the programming languages adopt practices from each other, therefore, the similarity of various code styles or comments is common.
• Hence, a PHP comment syntax does have similarities with certain programming languages.
• Furthermore, a PHP comment has three distinct styles or types, which are borrowed from three different languages.

2.1. PHP Comments Like C++ Style

1. Because PHP has its origin in C++, therefore, it adopts the comment syntax or style from C++.
2. Commonly, PHP took single line comments initiating with // form C++ Programming language.

<?php 
// A single line C++ type PHP comment. 
?>

2.2. PHP Comments Like C Style

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

<?php
/* A multi-line C-type PHP comment.
This line is also commented. */
?>

2.3. PHP comments Like PERL(Unix Shell Like)

1. Furthermore, PHP gained the comment style from the PERL programming language.
2. These PERL-style comments are single-line comments, just like the C++ style of comments.
3. The only difference is the symbol # is used to comment out a line of code.

<?php
# A single-line PERL-type PHP comment.
?>

3. Types of PHP Comments With Examples

3.1. PHP Single Line Comment

PHP assumed this single-line comment from C++ and PERL Programming languages. 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 the end of the line.
• The second type of single-line comment 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 including a comment.
• Further, if there is any HTML markup, it will be executed.

<?php
// This is a single-line PHP comment.

# This is another type of single-line PHP comment.
?>

3.2. PHP Multi-Line Comment

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

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

<?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
*/
?>

3.3. 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 star and slash */.
• Thus, comments nesting creates problems and sometimes may make a huge mess. Check the subsequent example for this.

<?php
/*
This is a comment that spans too 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 code. Each code block in a PHP file commences with a comment, and many code blocks also contain comments within the code blocks. Additionally, there is no limit to writing 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 the 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 comment blocks are left everywhere in code as mnemonics and reminders.
• Importantly, these comments support debugging by commenting on PHP code.
• Moreover, PHP multi-line comments are helpful when a developer shares his code with any other developer.
• Writing comments makes 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.
• PHP multi-line comments are also useful in writing code documentation and then generating it, as explained below.

5. What Is A Doc Block?

A doc block is any explanation of the code, within the code blocks, by using PHP comments. This explanation of code inside comments is called inline documentation. Moreover, a PHP doc block 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 doc block resembles the following illustration. Here a doc block is shown for a PHP class and PHP function only.

<?php
/**
* This is a doc block for class
*/
class Tuts
{
}
/**
* This is a doc block for the function
*/
function myFunction()
{
}