PHP Comments

Comments & Documentation in PHP

Comments are non-executable text lines ignored by the PHP parser. They are used to document code logic, explain complex algorithms, generate API documentation, and temporarily disable code during debugging.

Types of PHP Comments

PHP supports single-line, multi-line, and structured PHPDoc annotation comments.

// 1. Single-line C++ style comment

# 2. Single-line Shell/Unix style comment

/* 
 * 3. Multi-line block comment
 * Useful for long descriptions or disabling code blocks.
 */

/**
 * 4. PHPDoc comment block
 * @param string $email User email address
 * @return bool True if valid, false otherwise
 */

PHPDoc Annotation Structure

flowchart TD
    A["PHPDoc Block /** ... */"] --> B["Short Summary Description"]
    A --> C["@param Type $name Description"]
    A --> D["@return Type Description"]
    A --> E["@throws ExceptionType Description"]
    B & C & D & E --> F["IDE Code Completion & Doc Generator"]

Practical Code Example

<?php
declare(strict_types=1);

/**
 * Calculates order total including tax and discount rates.
 *
 * @param float $subtotal Base product total cost.
 * @param float $taxRate Tax percentage (e.g., 0.08 for 8%).
 * @param float $discountFlat Flat discount amount subtracted.
 * 
 * @return float Calculated final order total.
 */
function calculateOrderTotal(float $subtotal, float $taxRate = 0.05, float $discountFlat = 0.0): float
{
    // Apply discount first
    $discountedAmount = max(0.0, $subtotal - $discountFlat);

    // Calculate tax on discounted subtotal
    $taxAmount = $discountedAmount * $taxRate;

    # Return final rounded amount
    return round($discountedAmount + $taxAmount, 2);
}

// Single-line comment: Example invocation
$total = calculateOrderTotal(100.0, 0.10, 15.0);
echo "Calculated Order Total: $" . $total;

Best Practices

• Write Self-Documenting Code First: Use descriptive variable and function names so comments explain why, not what.
• Use PHPDoc for Complex Signatures: Annotate public methods and array structures so IDEs provide automatic IntelliSense.
• Remove Dead Commented Code Before Production: Clean up temporary debug comments before pushing code to version control.

Self-Check Challenge

Write a function calculateDiscount($price, $percentage) with a full PHPDoc docblock explaining its parameters and return type!