PHP — Comments

Single-line comments

Use // for a single-line comment. The rest of the line is ignored:

<?php
// This is a single-line comment
$x = 10; // Inline comment after code
$y = 20; // You can add notes at the end of a line too
?>

Single-line comments are the most common way to annotate code in PHP. Use them to explain why a line exists, not what it does when the code is obvious.

Multi-line comments

For longer explanations, use /* ... */:

<?php
/*
  This block spans multiple lines.
  Use it when a single line isn't enough
  to explain what the code does.
*/
$price = 99.99;
?>

Multi-line comments can also be written on a single line:

<?php /* This is a single-line multi-line comment */ ?>

Multi-line comments cannot be nested. Opening a second /* inside an existing block will cause an error:

<?php
/*
  This is valid.
  /* This is NOT valid — it will break. */
*/
?>

HTML documentation comments

PHP is often embedded in HTML. Use HTML comments for content that should remain invisible in the browser source:

<!-- This is an HTML comment — visible in page source -->
<!-- The <?php ... ?> tag stays hidden from viewers -->
<p>Hello, world!</p>

Note: HTML comments are visible in the page source. They are not secure for hiding sensitive information.

PHPDoc comments

PHPDoc is a standardized documentation format using /** ... */ blocks:

<?php
/**
 * Calculates the total price with tax.
 *
 * @param float $price The base price
 * @param float $taxRate The tax rate as a decimal
 * @return float The total price with tax applied
 */
function calculateTotal(float $price, float $taxRate): float {
    return $price * (1 + $taxRate);
}
?>

PHPDoc comments are parsed by IDEs and tools like PHPStan. They provide:

• Parameter types and descriptions via @param
• Return type via @return
• Exceptions via @throws
• Variable types via @var

Variable documentation

Use PHPDoc to document variables, especially when types are unclear:

<?php
/** @var string $userName The authenticated user's display name */
$userName = "Alice";

/** @var array<int, string> A list of product names */
$products = ["Laptop", "Mouse", "Keyboard"];
?>

When to comment

Follow these guidelines:

<?php
// GOOD: Explain WHY something is done
$x = $x & 0x7F; // Mask out the high bit for compatibility with legacy systems

// BAD: Explain WHAT the code does (redundant)
$x = $x & 0x7F; // Bitwise AND with 0x7F

// GOOD: Document complex logic
$retryDelay = min(300, pow(2, $attempt) * 100); // Exponential backoff, capped at 300ms

// GOOD: Mark TODO items
// TODO: Replace with database query once migration is complete
$config = parse_ini_file("config.ini");
?>

Comment best practices

Practice	Reason
Write comments before changing code	Explains intent to future readers
Use TODO/FIXME/HACK markers	Makes issues searchable with grep
Keep comments near their code	Avoids stale comments when code moves
Delete comments that no longer apply	Dead comments confuse readers
Use PHPDoc for public functions	Enables IDE auto-complete and static analysis

Mini Practice

Write PHP code that:

1. Declares two variables with // inline comments explaining each
2. Creates a /** */ PHPDoc block for a function that accepts two integers and returns their sum
3. Writes a /* */ multi-line comment explaining the purpose of a section of code

Up Next

In the next lesson, you'll learn about Variables — how to declare and use variables in PHP.