Chapter 9: Comments

A comment is a note to a human reader. The compiler throws it away before the program is built, so it costs nothing at runtime and can never change what your code does.

Line comments

Everything from // to the end of the line is ignored:

$rate = 0.19;   // VAT, as of 2026
echo $rate;   // this line is not part of the program

Block comments

For something that spans several lines, wrap it in /* ... */:

/*
 * This used to charge a flat fee.
 * Kept for reference until the pricing page is rewritten.
 */
$price = 9.99;
echo $price;

A block comment cannot nest: the first */ ends it, no matter what is inside.

Doc comments

A block comment that starts with an extra * is the conventional way to document a function or a class. It means the same thing as a normal comment — the style simply says "this describes the thing below":

/**
 * Returns the total price including VAT.
 */
function total(float $net): float {
    return $net * 1.19;
}

echo total(100.0);

Turning code off temporarily

Comments are the standard way to park a line while you experiment:

echo "before";
// echo "skipped for now";
/* echo "also skipped"; */
echo "after";

Prefer commenting out to deleting while you are exploring — but delete it again before you commit. A file full of commented-out experiments is noise for whoever reads it next.

What is worth commenting

• Why, not what: // 19% VAT, fixed by law beats // set rate to 0.19.
• Non-obvious constraints: why a number is magic, why something must not be reordered.
• Markers for unfinished work: // TODO: or // FIXME: are easy to search for later.
• Not: what the next line obviously does. $i++; // increment i adds noise.