PHP Comments: Single-line, Multi-line, and DocBlock Explained with Examples

Introduction

When writing PHP code, adding comments is one of the most important best practices.
Comments help explain what your code does, making it easier to understand, maintain, and debug — both for you and others who read your code later.

In PHP, comments are non-executable lines that the interpreter completely ignores during program execution. They are meant for humans, not machines.

In this lesson, we’ll explore:

  • Types of PHP comments

  • How to use them effectively

  • Examples for each type

  • Why comments are crucial for good programming habits

What Are Comments in PHP?

A comment in PHP is a piece of text within your script that’s ignored by the PHP engine. It’s useful for:

  • Describing what a code block does

  • Temporarily disabling code during testing

  • Adding notes or documentation for future reference

Comments don’t affect the execution or output of a PHP program.

Types of Comments in PHP

PHP supports three types of comments:

  1. Single-line comments

  2. Multi-line comments

  3. DocBlock (Documentation) comments

Let’s look at each type in detail.

Single-line Comments in PHP

Single-line comments are used to explain a specific line of code.
Everything after the comment symbol on that line is ignored by PHP.

You can create single-line comments using either:

  • Double slash (//)

  • Hash symbol (#)

 Syntax:

 
// This is a single-line comment using double slashes
# This is a single-line comment using hash symbol

Example:

 

<?php
// Define a variable
$name = "Arvinder";
# Display the name
echo "Hello, $name!"; ?>

Output:

 
Hello, Arvinder!

Explanation:
The comment lines are ignored by PHP — they only serve as notes for the developer.

Multi-line Comments in PHP

Multi-line comments are used when you need to write longer explanations that span multiple lines.

They begin with /* and end with */.

 Syntax:

 
/*
This is a multi-line comment.
It can span across several lines.
Used to describe a block of code or function.
*/

Example:

 

<?php
/* The following code calculates the
sum of two numbers and prints the result. */
$a = 10;
$b = 20;
$sum = $a + $b;
echo "The sum is: $sum";
?>

Output:

 
The sum is: 30

Explanation:
Multi-line comments are perfect for explaining logic, algorithms, or sections of complex code.

DocBlock (Documentation) Comments in PHP

DocBlock comments are special multi-line comments used for documentation purposes, especially when working with large projects or frameworks.

They begin with /** and end with */.
Inside, you can include annotations like @param, @return, and @author.

These are recognized by PHPDocumentor and other tools to generate automatic documentation.

 Syntax:

 
/**
* Brief description of the function
*
* Detailed explanation goes here.
*
* @param type $variable Description
* @return type Description
*/

Example:

 

<?php
/**
* Calculate the area of a rectangle
*
* This function takes length and width as parameters
* and returns the calculated area.
*
* @param float $length The length of the rectangle
* @param float $width The width of the rectangle
* @return float The area of the rectangle
*/
function calculateArea($length, $width) {
return $length * $width;
}
echo "Area: " . calculateArea(10, 5);
?>

Output:

 
Area: 50

Explanation:
DocBlock comments are essential for professional coding and help tools and IDEs (like VS Code, PhpStorm) show auto-completion and documentation.

Why Use Comments in PHP?

Comments make your code:

  • Readable: Helps others (and you) understand what the code does

  • Maintainable: Easier to fix or update in the future

  • Debuggable: You can disable sections temporarily by commenting them out

  • Documented: DocBlocks serve as live documentation for projects

Best Practices for Writing Comments

  • Use clear and concise language.
  • Don’t over-comment obvious code (e.g., // add 1 to x for $x++).
  •  Update comments if the code changes.
  • Use DocBlock for functions, classes, and APIs.
  • Keep comments meaningful and aligned with coding standards.