Understanding PHP Comments

Comments are notes you leave inside your source code that PHP ignores when it runs the program. They exist purely for humans — to explain why a piece of code does what it does, to leave reminders, or to temporarily disable code while debugging. This guide covers every comment syntax PHP supports, when to use each one, and the practices that keep comments helpful instead of noise.

This chapter assumes you already know how to write basic PHP. If not, start with the PHP Syntax and PHP Variables chapters first.

What are PHP Comments?

A comment is text in your code that the PHP engine does not execute. When PHP parses a file, it skips over comments entirely — they never affect output, performance, or behavior. They serve as documentation for whoever reads the code next, including your future self.

PHP supports three comment styles, which fall into two groups:

• Single-line comments, written with // or #.
• Multi-line (block) comments, written with /* ... */.

PHP inherits the // and /* */ styles from C and Java, and the # style from shell scripts and Perl — so whatever language you came from, one of these will feel familiar.

Single-Line Comments

A single-line comment makes PHP ignore the rest of the current line. PHP gives you two interchangeable markers for this: // (C-style) and # (shell-style). They behave identically — pick one and stay consistent within a project.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

The comment ends at the line break, so the echo statements still run. The script above prints Hello, world! Goodbye! Done.

Multi-Line Comments

A multi-line comment starts with /* and ends with */. Everything between those markers is ignored, even across many lines. Use it for longer explanations or to comment out a block of code at once.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

The two echo statements print Visible output — still works; everything inside /* ... */ is skipped.

Gotcha — block comments do not nest. PHP stops the comment at the first */ it finds. If you wrap code that already contains a /* ... */ comment, the outer block ends early and the leftover */ causes a parse error. To disable a chunk of code that already has block comments, use // or # on each line instead.

Why Use PHP Comments?

PHP comments are an important tool for developers, as they help to make code easier to understand and maintain. By adding comments to your code, you can explain the purpose of specific lines of code, or provide additional information about the code. This makes it easier for other developers to understand and maintain your code, and also helps you to remember what your code does if you come back to it later.

How to Use PHP Comments

To add a comment to your PHP code, simply start the line with either two forward slashes (for single-line comments) or a forward slash and an asterisk (for multi-line comments). It's important to choose the appropriate type of comment based on the size and complexity of the code you are commenting on.

It's also important to make sure that your comments are clear and concise, and that they provide meaningful information about the code. Avoid using comments to simply repeat the code, or to state the obvious. Instead, focus on providing information that is not immediately apparent from the code.

Commenting Out Code While Debugging

One of the most practical uses of comments is temporarily disabling code without deleting it. Prefix a line with // or #, or wrap several lines in /* ... */, to take them out of the program:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Remember the no-nesting rule above: if the code you want to disable already contains a /* */ block, comment it out line-by-line with // instead.

Documentation Comments (PHPDoc)

Beyond plain comments, the PHP ecosystem has a documentation convention called PHPDoc. It is a block comment that starts with /** (two asterisks) and uses @ tags to describe functions, parameters, and return values. IDEs and tools like phpDocumentor read these to provide autocompletion and generate API docs.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc is technically just a normal /* */ comment to the PHP engine — it has no runtime effect — but following the convention makes your functions far easier for editors and teammates to understand. You will see it heavily in the PHP Functions chapter.

Best Practices for PHP Comments

Here are some best practices to follow when using PHP comments:

• Use clear and concise language in your comments
• Avoid repeating the code in your comments — explain why, not what
• Focus on providing information that is not immediately apparent from the code
• Use appropriate levels of detail in your comments
• Keep your comments up to date as your code evolves — a stale comment is worse than none
• Prefer self-explanatory variable and function names over comments that explain unclear ones

Conclusion

PHP comments are an essential tool for developers, allowing them to make their code easier to understand and maintain. PHP gives you three syntaxes — // and # for single lines, and /* ... */ for blocks — plus the PHPDoc convention for documenting functions. By following the best practices outlined in this article, you can make the most of PHP comments and ensure that your code is well-documented and easy to understand for other developers.

To keep learning, move on to PHP Variables and PHP Operators.

Practice