What are comments in PHP and why do we use them ? » Decode Web

Everybody knows about comments because it is the first thing which is taught in schools and colleges. We were told that commented code is never executed in a program, it is correct but not completely, I will show you in details in this post but let us go through its definition first.

Comments, be in PHP or any other programming language is the text in source code which is not executed when a program is compiled, interpreted or run, that is, the text we write in comments are not visible to end users. Moreover, a comment is useful to share an idea or working of a code block in a team of developers working on the same project.

Moreover, a code block can be anything, a single line of code, or a function or a class or the file itself. They are even important for solo developers since a comment can remind the idea or algorithm a developer applied a long back ago. Since this post is regarding PHP then I am supposed to give you more details on PHP comments.

PHP supports ‘C’, ‘C++’ and Unix shell-style (Perl style) comments. As per the PHP standards, there are three (3) ways to comment out code.

1. In line / Single line
2. Multi-line
3. Documentation / DocBlock
4. Todo comment (Bonus)

In line or single line comment is denoted as // (double forward slashes). The single line after // becomes the text for comment. For example.

<?php echo "Hello World"; //This is single line comment?>

In phpstorm IDE, select the line or put cursor on the line you want to comment and press Ctrl+/

Multi-line comments are used when we want to comment out a whole block of lines of code. The comment text is enclosed in /* and */. For example

<?php

/*echo "This is the first line of code";
echo "This is the second line of code"*/

?>

In phpstorm IDE, select the lines from start to till you want to comment and press Ctrl+shift+/

This is a different kind of PHP comment that has its own standard — it is called DocBlock. DocBlocks are blocks of texts which are used to generate documentation using phpDocumentor also known as phpDoc. Interestingly, they are more important and we must use them if we are developing a complex software product, everything must be documented in that case.

A DocBlock is a modified version of Multi line comment and can be easily identified by its distinct style. For example.

<?php
/**
* This comment will be added as text
* for DummyClass in documentation
*/
Class DummyClass{
    /**
      * This comment will be added as text
      * for DummyFunction in documentation
      */
    Public function dummyFunction()
    {
        //This comment will not be added in documentation
    }
}

As you can see, DocBlock comments start with /** and ends with */

Keyboard short-cut for DocBlock

In phpstorm IDE, put the cursor above the class or function name, type /** and press enter, it will automatically generate DocBlock with some additional field which you can remove for the time being because we will see PHP documentation in another article.

Apart from standard types of comments in php, I also use one different type of comment which is ToDo comment.

todo comments are nothing but single line comments but after // we add todo. For example 

<?php

//todo This part I will see after coming from vacation

?>

In phpsorm, press Ctrl + E and select TODO, you will see all the todos which needs your attention.

Conclusion

So friends, we now came to the end of this post where we seen different kinds of comments in PHP and their usage in our code and documentation. Which type did you find most useful, tell me in the comments below.