PHP Comments

PHP Comments: Explaining Intent and Documenting Code

PHP comments are non-executable notes inside your .php scripts that the PHP parser completely skips. Developers use comments to explain why a rule exists, disable lines during debugging, and give IDEs type information via PHPDoc blocks.

Three Comment Styles in PHP

PHP supports two single-line comment formats and one multi-line block format. Choose // for short inline notes and /* ... */ for longer explanations.

<?php
declare(strict_types=1);

// Single-line comment explaining a business threshold
$freeShippingMin = 50.00;

/*
 * Multi-line comment:
 * Apply a 10% loyalty discount only after verifying
 * the customer account has at least three paid orders.
 */
$discountRate = 0.10;
$subtotal = 80.00;
$finalPrice = $subtotal - ($subtotal * $discountRate);

echo "Final price: $" . number_format($finalPrice, 2) . PHP_EOL;

PHP also accepts # for single-line shell-style comments, though modern PHP style guides (PER Coding Style) prefer // for consistency. Note that # followed by square brackets (#[Attribute]) is parsed as a PHP 8 attribute, not a comment.

Writing Helpful PHPDoc Blocks

PHPDoc comments start with /** and sit right above classes, properties, and functions. Tools like PHPStan, Psalm, and VS Code read these tags to catch type mismatches before your code runs.

<?php
/**
 * Calculate invoice total after applying tax.
 *
 * @param float $amount Base order amount before tax
 * @param float $taxRate Tax rate as a decimal (for example, 0.08)
 * @return float Final rounded invoice amount
 */
function calculateInvoiceTotal(float $amount, float $taxRate): float
{
    return round($amount * (1 + $taxRate), 2);
}

echo calculateInvoiceTotal(120.00, 0.08) . PHP_EOL;

Common Mistakes to Avoid

• Stating the obvious: Writing // increment counter above $count++ adds clutter. Explain why the counter increments instead.
• Nesting /* ... */ blocks: PHP does not support nested block comments. Wrapping existing /* */ blocks inside another /* */ causes a syntax error.
• Leaving commented-out dead code in commits: Delete obsolete code instead of hiding it in comments; Git history already preserves old versions.

Frequently Asked Questions

Do PHP comments slow down script execution?

No. The PHP compiler strips all comments when compiling scripts into bytecode, and OPcache caches the compiled opcodes without comments.

What is the difference between /* and /**?

/* begins a standard multi-line comment ignored by tools. /** begins a PHPDoc block that documentation generators and static analyzers parse.

When should I use # comments in PHP?

Avoid # for regular comments in PHP 8 so they are never confused with PHP 8 attributes like #[Route('/home')]. Use // instead.