PHP Comments Tutorial

What is a comment?

Commenting is a way for a programmer to document their code and to enhance its readability.

PHP comments are ignored by the interpreter, which means the interpreter won’t try to execute any text written inside a comment.

In general, our code should be written cleanly and clearly enough so that it’s obvious as to what the code does.

In most cases our code won’t need comments, but there are situations where we should include comments.

• When learning, we want to comment most of what we're doing or what specific code is doing.

  We're not yet used to how a language operates and even if we know another language, PHP might behave differently to what we're used to. It helps us understand and remember code functionality.

  It's recommended to comment code extensively in your own words when learning programming or when learning a new programming language.

• When we're working on projects as part of a group we want to comment our code in such a way that other programmers immediately understand what's going on.

  One programmer shouldn't need to ask another what their code does, it should be obvious or commented. This helps to avoid confusion and increase productivity.

• When using external libraries it may be useful to comment what certain things do or why they are used so that it's not necessary to go back and forth to the library's documentation for lookup in the future.
• When we're working with complex code it may not be immediately clear what the code is doing. Commenting in such a case is useful to quickly see what pieces of code is doing or what it's for.
• In some cases we may want to temporarily remove a piece of code to either try something different, or to debug problem areas.
• When planning to create API Documentation.

How to comment PHP code

PHP supports C, C++ and Unix shell (Perl style) comments.

C and C++ style single line comments in PHP

A single line comment occupies its own line. Everything up to a new line will be a comment and PHP will ignore it.

With a C, C++ style comment we write two forward slashes // followed by some words.

 // comment

<?php

// This is a single line comment
$var = "Hello World";

?>

Single line comments can also be written on the same line as code, but it must be after the code. Everything up to a new line will then be a comment.

<?php

$var = "Hello World"; // Comment on the same line, after code

?>

C and C++ style multi-line comments in PHP

We can create comments that span across multiple lines, using open and close comment tags.

An open comment tag is a forward slash immediately followed by an asterisk, /* . A closing comment tag is a asterisk immediately followed by a forward slash, */ .

/* open tag

close tag */

<?php

/* This is a multi-
line comment. */

?>

A big benefit of multiline comments is that we can use them inside code statements because they are contained within the comment tags.

<?php

$isSomething = true;
$isSomethingElse = true;

if($isSomething /* && $isSomethingElse */) {
    echo "found the bug!!";
}

?>

Unix shell style single line comments in PHP

A Unix shell style single line comment works the same as a C, C++ single line comment, except that instead of two forward slashes we write an octothorp # .

If you come from a language such as Perl or Python, this style of commenting will be familiar.

 # Unix shell style single line comment

<?php

# This is a single line comment
$var = "Hello World";

$var2 = "Hello there"; # alternative

?>

Which comment style should we use

There are specific cases where it’s better to use the Unix shell style comment over C, C++ comments and vice versa.

<?php

# Unix style works
# $a = '*/';

// C, C++ style single line works
// $b = '*/';

/* C, C++ style multi-line breaks code

$c = '*/';

*/

?>

In the example above the closing comment tag */ is used within a regular expression, breaking the code. In such a case the Unix shell or C, C++ single line comment style will not break the code.

The opposite will be true if we use something like the closing PHP tag ?> in a regular expression.

<?php

/* C, C++ style multi-line works

$c = '#//?>';

*/

# Unix style breaks code
# $a = '#//?>';

// C, C++ style single line breaks code
// $b = '#//?>';

?>

It’s up to your personal preference and the code you’re working with to determine the style of comments you use.

Comments of other languages

It’s worth it to note that other language comments, such as HTML comments, have no meaning to the PHP parser.

<!-- HTML comment
<?php echo "This code will still be parsed"; ?>
-->

If we run the example above in a file with a .php extension, the string will still be printed.

Create API Documentation from comments

We can generate API Documentation directly from comments by using PHPDocumentor .

To do this we have to use JavaDoc style comments. A JavaDoc style comment is similar to a multi-line comment, except that the first line has two asterisks and generally have no text.

/**
 * JavaDoc style commenting
 * that can be converted to
 * documentation by PHPDocumentor
 */

You may never want or need official type documentation for your PHP code. If you do want or need it later on, consider PHPDocumentor or something similar to speed up the process.

Summary: Points to remember

• Single line comments can only span one line.
• Multi-line comments need open /* and a close */ tags.
• Unix shell style comments is supported in PHP and uses the octohorp # instead of two slashes //. Unix shell style comments can be used when something like regex prevents normal comments.
• Other language comments, such as HTML, will still be parsed by PHP.
• JavaDoc style comments can be used to create API Documentation with PHPDocumentor.