LearnContact
Lesson 815 min read

Comments

Learn how to write single-line, multi-line, and documentation comments in PHP, and why good comments explain the why, not the what.

Introduction

Code is read far more often than it is written. Weeks or months after you write a script, you — or a teammate — will come back to it needing to understand not just what it does, but why it does it that way. Comments are how you leave that explanation behind.

PHP gives you three ways to write comments: two styles for single-line notes, one for multi-line blocks, and a special documentation format called a docblock. This lesson covers all of them, along with when — and when not — to use comments.

What You Will Learn
  • How to write single-line comments with // and #.
  • How to write multi-line comments with /* */.
  • Why good comments explain reasoning, not just restate code.
  • What docblocks are and how tools and IDEs use them.

Single-Line Comments

A single-line comment tells PHP to ignore everything from a marker to the end of that line. PHP supports two markers for this: // and #.

single-line.php
<?php
    // Calculate the total price including tax
    $price = 500;
    $tax = $price * 0.18; // 18% GST

    # This line uses the alternate hash-style comment
    $total = $price + $tax;

    echo $total;
?>
Output
590
Which One Should I Use?

Both // and # work identically. The // style is far more common in the PHP community and used throughout the official manual, so most style guides recommend sticking with it for consistency.

Multi-Line Comments

When you need to comment out several lines at once, or write a longer explanation, use the /* */ style. Everything between /* and */ is ignored, no matter how many lines it spans.

multi-line.php
<?php
    /*
        This block calculates a student's final grade
        based on their average marks across three subjects.
        Passing threshold is 40 marks out of 100.
    */
    $average = (72 + 65 + 80) / 3;

    echo $average;
?>
Output
72.333333333333
No Nesting Allowed

Multi-line comments cannot be nested. Writing /* outer /* inner */ still ends at the first */, which usually leaves a stray */ that causes a syntax error.

A very common use of /* */ during development is temporarily disabling a block of code without deleting it.

disable-code.php
<?php
    echo "Step 1 complete\n";

    /*
    echo "Step 2 (temporarily disabled)\n";
    echo "Step 3 (temporarily disabled)\n";
    */

    echo "Step 4 complete\n";
?>
Output
Step 1 complete
Step 4 complete

Why Comment? Explain the Why, Not the What

A common beginner mistake is writing comments that simply restate what the code already says clearly. Good comments add information the code cannot express on its own: the reasoning, the trade-off, or the business rule behind a decision.

Weak Comment (the "what")

  • // add 1 to $count
  • $count = $count + 1;

Useful Comment (the "why")

  • // Retry counter must increase before each
  • // attempt so the loop below terminates
  • $count = $count + 1;
A Good Test

Before writing a comment, ask: "Could a reader figure this out just by reading the code itself?" If yes, the comment is probably unnecessary. If the reasoning, history, or intent is not visible in the code, that is worth commenting.

Docblocks: Documentation Comments

PHP also supports a special comment style, /** ... */ (note the extra asterisk), known as a docblock. Docblocks look like ordinary multi-line comments to the PHP interpreter, but IDEs and documentation tools like phpDocumentor read them to provide autocompletion, type hints, and generated documentation.

docblock.php
<?php
    /**
     * Calculates the total price after applying tax.
     *
     * @param float $price The base price before tax.
     * @param float $taxRate The tax rate as a decimal (e.g. 0.18).
     * @return float The final price including tax.
     */
    function calculateTotal($price, $taxRate) {
        return $price + ($price * $taxRate);
    }

    echo calculateTotal(500, 0.18);
?>
Output
590
Not Just for Big Projects

Docblocks are especially valuable once you start writing functions with several parameters. Most modern code editors show the docblock as a tooltip while you are calling the function elsewhere in your code, saving you a trip back to its definition.

Common Mistakes

Avoid These Mistakes
  • Trying to nest /* */ comments inside one another.
  • Writing comments that only repeat what the code obviously already says.
  • Leaving large blocks of commented-out dead code in a file indefinitely instead of deleting it (version control already remembers old code for you).
  • Forgetting that anything after // or # on that line is ignored, including code you meant to keep — a common source of "why isn't this running?" bugs.

Best Practices

  • Prefer // for single-line notes and reserve /* */ for larger blocks or temporarily disabling code.
  • Write comments that explain why, not what.
  • Add docblocks to functions and classes you expect others (or future you) to reuse.
  • Remove stale comments and dead commented-out code during cleanup — rely on version control history instead.

Frequently Asked Questions

Is there a difference between // and # in PHP?

No functional difference — both create a single-line comment. // is the more widely used convention in PHP code.

Do comments slow down my PHP script?

No. Comments are stripped out before execution and have no measurable effect on performance.

What exactly is a docblock used for?

A docblock is a specially formatted /** */ comment that documents a function, class, or property. IDEs and tools like phpDocumentor parse it to show hints, types, and generate reference documentation.

Can I use a multi-line comment for just one line?

Yes, /* like this */ works fine on a single line, though // is more conventional for single-line notes.

Key Takeaways

  • Single-line comments use // (preferred) or #.
  • Multi-line comments use /* */ and cannot be nested.
  • Good comments explain why the code exists, not what it literally does.
  • Docblocks (/** */) are documentation comments read by IDEs and tools like phpDocumentor.

Summary

Comments let you leave notes for humans without affecting how PHP executes your code. Use // or # for quick single-line notes, /* */ for longer explanations or temporarily disabling code, and docblocks when you want IDEs and documentation tools to understand your functions.

With comments covered, you are ready to move on to variables — the fundamental building block for storing and working with data in PHP.

Lesson 8 Completed
  • You can write single-line and multi-line comments.
  • You understand why good comments explain reasoning, not restate code.
  • You know what a docblock is and why IDEs use them.
Next Lesson →

Variables