4. PHP Comments

What you will learn

• The three ways to write a PHP comment
• How to switch code off temporarily
• How to write helpful comments
• What comments must never contain

What is a comment?

A comment is a note in your code that PHP ignores. Comments explain your thinking to the next reader, who may well be you in six months.

Single-line comments

Use // or #. Everything after it on that line is ignored. Most people prefer //.

<?php
// This is a comment
echo "Visible. ";   // a comment after code
# This style also works
echo "Still visible.";

Multi-line comments

Start with /* and end with */. Everything in between is ignored, across as many lines as you like.

<?php
/*
  Welcome page
  Author: Sam
  Shows a greeting to the visitor.
*/
echo "Welcome!";

Documentation comments

A comment that starts with /** is a docblock. Editors and tools read these to describe functions. You will see them in WordPress code and professional projects.

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

You will learn about functions in a later lesson. For now, notice how the comment explains what the function expects and returns.

Switching code off

Put // in front of a line to disable it without deleting it. This is a quick way to find which line causes a problem.

<?php
echo "Line one. ";
// echo "Line two (switched off). ";
echo "Line three.";

In Visual Studio Code, select the lines and press Ctrl+/ to add or remove comment marks.

Comments in the middle of a line

A multi-line comment can sit inside a line, though this is unusual and can make code harder to read.

<?php
$total = 10 /* ten items */ + 5;
echo $total;

PHP comments versus HTML comments

This difference matters for privacy.

<!-- Anyone can read this in "View page source" -->
<?php // Nobody can see this: PHP removes it ?>
<p>Hello</p>

<!-- Anyone can read this in "View page source" -->

<p>Hello</p>

Use PHP comments for notes about your code, so visitors never see them.

Writing good comments

• Explain why, not the obvious what. The comment “adds 1” above $i++ helps nobody.
• Keep them short, and update them when the code changes. A wrong comment is worse than none.
• Use a comment at the top of a file to say what it is for.
• Remove old commented-out code before publishing.

<?php
// Weak: repeats the code
// Set the tax rate to 0.2
$tax_rate = 0.2;

// Better: explains the reason
// Standard rate used for all products except books
$tax_rate = 0.2;

Common mistakes

• Forgetting the closing */, so the rest of the file is ignored.
• Nesting multi-line comments. A comment ends at the first */, so commenting out code that already holds a /* */ comment breaks.
• Using HTML comments for private notes.
• Leaving secrets in comments.
• Writing comments that no longer match the code.

<?php
echo "Apple ";
echo "Banana ";
echo "Cherry";

<?php
// Prints a short list of fruit
echo "Apple ";
// echo "Banana ";
echo "Cherry";

Summary

• Use // or # for one line, and /* */ for several. /** */ documents functions.
• PHP comments are private. HTML comments are public.
• Explain the why, keep comments current, and never store secrets in them.