Comments (// # /* */ and PHPDoc)

// Single-line comment (// style)
// This line is a comment

# Single-line comment (# style)
# This line is also a comment

$value = 100; // Inline comment at end of line

/* Block comment */
/*
  A multi-line comment.
  Used for longer explanations.
*/

/**
 * PHPDoc comment.
 * Written directly before a function, class, or property.
 *
 * @param type $argName Description of the argument
 * @return type Description of the return value
 * @var type Description of the property
 */

Syntax	Type	Description
//	Single-line comment	Everything from『//』to the end of the line becomes a comment. The most commonly used style.
#	Single-line comment	Everything from『#』to the end of the line becomes a comment. A shell script-style notation with the same behavior as『//』.
/* ... */	Block comment	Everything between『/*』and『*/』becomes a comment. Used for multi-line explanations or temporarily disabling code.
/** ... */	PHPDoc comment	A block comment beginning with『/**』. Recognized by IDEs and documentation generation tools, allowing type information and descriptions to be recorded.

Tag	Location	Description
@param	Functions / methods	Documents the type and description of an argument. Format: 『@param type $argName description』.
@return	Functions / methods	Documents the type and description of the return value. Format: 『@return type description』.
@var	Class properties	Documents the type of a property. Format: 『@var type description』.
@throws	Functions / methods	Documents exception classes that may be thrown.
@param array<type>	Functions / methods	Specifies the element type of an array explicitly. Example: 『@param array<string>』indicates an array of strings.

Since PHP 7, type declarations (type hints) can be written for function arguments and return values. Type hints are enforced at runtime, whereas PHPDoc is only an annotation and has no effect at runtime. The two are used as follows.

Situation	Preferred approach
Enforcing the type of an argument or return value	Type hint (runtime checked)
Indicating the element type of an array	PHPDoc (e.g.『@param array<string>』). Type hints can only express『array』without element type information.
Indicating a property type (PHP 7.3 and earlier)	PHPDoc (『@var type』)
Improving IDE autocompletion and static analysis	Combine type hints with PHPDoc.

comment_basic.php

<?php
// Basic usage of single-line and inline comments
// Storing sorcerer information from Jujutsu Kaisen into variables

$sorcererName = "五条悟"; // Sorcerer name
$grade = "特級"; // Sorcerer grade
$cursedTechnique = "無下限呪術"; // Technique name

# The # style single-line comment. Same behavior as //
# Displaying the variable contents

echo $sorcererName . "（" . $grade . "）: " . $cursedTechnique . "\n";

/*
  Block comments span multiple lines and can be used for longer explanations
  or to temporarily disable code.
  The following line is currently disabled.

  echo "This line is not executed.\n";
*/

Running the code produces the following output:

php comment_basic.php
五条悟（特級）: 無下限呪術

comment_phpdoc_function.php

<?php
/**
 * Generates an introduction string for a sorcerer.
 *
 * @param string $name  Sorcerer's name
 * @param string $grade Sorcerer grade (特級, 1級, 2級, etc.)
 * @param int    $power Cursed energy level (non-negative integer)
 * @return string Formatted profile string
 */
function formatSorcererProfile(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "術師）/ 呪力量: " . $power;
}

// Writing @param / @return in PHPDoc enables IDE argument type hints and descriptions
echo formatSorcererProfile("伏黒恵", "1級", 850) . "\n";
echo formatSorcererProfile("釘崎野薔薇", "1級", 720) . "\n";
echo formatSorcererProfile("虎杖悠仁", "特級", 9800) . "\n";

Running the code produces the following output:

php comment_phpdoc_function.php
伏黒恵（1級術師）/ 呪力量: 850
釘崎野薔薇（1級術師）/ 呪力量: 720
虎杖悠仁（特級術師）/ 呪力量: 9800

comment_phpdoc_class.php

<?php
/**
 * Class representing a sorcerer.
 * Manages name, grade, and techniques together.
 */
class Sorcerer {

	/**
	 * @var string Sorcerer's name
	 */
	public string $name;

	/**
	 * @var string Sorcerer grade
	 */
	public string $grade;

	/**
	 * @var array<string> List of available techniques
	 */
	public array $techniques;

	/**
	 * Constructor.
	 *
	 * @param string        $name       Sorcerer's name
	 * @param string        $grade      Sorcerer grade
	 * @param array<string> $techniques List of techniques
	 */
	public function __construct(string $name, string $grade, array $techniques) {
		$this->name = $name;
		$this->grade = $grade;
		$this->techniques = $techniques;
	}

	/**
	 * Returns formatted sorcerer information.
	 *
	 * @return string Sorcerer info string
	 */
	public function describe(): string {
		$techList = implode("・", $this->techniques);
		return $this->name . "（" . $this->grade . "）術式: " . $techList;
	}
}

$sorcerer = new Sorcerer("五条悟", "特級", ["蒼", "赫", "紫"]);
echo $sorcerer->describe() . "\n";

$sorcerer2 = new Sorcerer("夏油傑", "特級", ["呪霊操術"]);
echo $sorcerer2->describe() . "\n";

Running the code produces the following output:

php comment_phpdoc_class.php
五条悟（特級）術式: 蒼・赫・紫
夏油傑（特級）術式: 呪霊操術

comment_phpdoc_throws.php

<?php
/**
 * Searches for sorcerers by grade.
 * Throws an exception if the grade is invalid.
 *
 * @param  array<string, string> $sorcerers Associative array of sorcerer name => grade
 * @param  string                $targetGrade Grade to search for
 * @return array<string> Array of matching sorcerer names
 * @throws \InvalidArgumentException When the grade is an empty string
 */
function findByGrade(array $sorcerers, string $targetGrade): array {
	// An empty grade string is invalid, so throw an exception
	if ($targetGrade === "") {
		throw new \InvalidArgumentException("Please specify a grade.");
	}

	$result = [];
	foreach ($sorcerers as $name => $grade) {
		if ($grade === $targetGrade) {
			$result[] = $name; // Add matching sorcerer name to result array
		}
	}
	return $result;
}

// Associative array of sorcerer name => grade
$sorcerers = [
	"五条悟" => "特級",
	"夏油傑" => "特級",
	"伏黒恵" => "1級",
	"釘崎野薔薇" => "1級",
	"虎杖悠仁" => "特級",
];

$tokkyuList = findByGrade($sorcerers, "特級");
echo "Special-grade sorcerers: " . implode("、", $tokkyuList) . "\n";

$ichikyuList = findByGrade($sorcerers, "1級");
echo "Grade-1 sorcerers: " . implode("、", $ichikyuList) . "\n";

Running the code produces the following output:

php comment_phpdoc_throws.php
Special-grade sorcerers: 五条悟、夏油傑、虎杖悠仁
Grade-1 sorcerers: 伏黒恵、釘崎野薔薇

Nesting block comments

Block comments (/* ... */) cannot be nested. The inner */ ends the comment, and code after it causes a syntax error.

ng_comment_nested.php

<?php
/*
  /* Nested block comment */
  This is intended to be a comment, but the inner */ ends it
*/
echo "五条悟（特級）: 無下限呪術\n";

Running the code produces the following output:

php ng_comment_nested.php
Parse error: syntax error, unexpected token "*" in ng_comment_nested.php on line 5

To include comments within a block comment, use single-line comments (//) inside it, or avoid nesting by consolidating into one block.

ok_comment_nested.php

<?php
/*
  // Single-line comments can be written inside block comments
  This is inside a block comment
*/
echo "五条悟（特級）: 無下限呪術\n";

Running the code produces the following output:

php ok_comment_nested.php
五条悟（特級）: 無下限呪術

Writing PHPDoc @param tags out of order with the actual arguments

PHPDoc @param tags do not technically need to match the argument order, but a mismatch makes the documentation harder to read, and some IDEs or static analysis tools may produce incorrect completions or warnings.

ng_phpdoc_order.php

<?php
/**
 * @param int    $power Cursed energy level
 * @param string $grade Sorcerer grade
 * @param string $name  Sorcerer's name
 * @return string
 */
function describeSorcerer(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "）/ 呪力量: " . $power;
}

echo describeSorcerer("虎杖悠仁", "特級", 9800) . "\n";

Running the code produces the following output:

php ng_phpdoc_order.php
虎杖悠仁（特級）/ 呪力量: 9800

Write PHPDoc @param tags in the same order as the function arguments.

ok_phpdoc_order.php

<?php
/**
 * @param string $name  Sorcerer's name
 * @param string $grade Sorcerer grade
 * @param int    $power Cursed energy level
 * @return string
 */
function describeSorcerer(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "）/ 呪力量: " . $power;
}

echo describeSorcerer("虎杖悠仁", "特級", 9800) . "\n";
echo describeSorcerer("伏黒恵", "1級", 850) . "\n";

Running the code produces the following output:

php ok_phpdoc_order.php
虎杖悠仁（特級）/ 呪力量: 9800
伏黒恵（1級）/ 呪力量: 850

Writing just array in PHPDoc without specifying the element type

When only array is written as the type hint or in PHPDoc, IDEs and static analysis tools cannot determine what type of values the array contains. When the element type is known, supplement it in PHPDoc.

ng_phpdoc_array.php

<?php
/**
 * @param array $names Array of sorcerer names
 * @return array Result array
 */
function listSorcerers(array $names): array {
	return array_map(fn($n) => "Sorcerer: " . $n, $names);
}

$result = listSorcerers(["五条悟", "夏油傑"]);
foreach ($result as $line) {
	echo $line . "\n";
}

Running the code produces the following output:

php ng_phpdoc_array.php
Sorcerer: 五条悟
Sorcerer: 夏油傑

Using array<string> in PHPDoc to specify the element type improves IDE autocompletion accuracy.

ok_phpdoc_array.php

<?php
/**
 * @param array<string> $names Array of sorcerer names
 * @return array<string> Result array
 */
function listSorcerers(array $names): array {
	return array_map(fn($n) => "Sorcerer: " . $n, $names);
}

$result = listSorcerers(["五条悟", "夏油傑"]);
foreach ($result as $line) {
	echo $line . "\n";
}

Running the code produces the following output:

php ok_phpdoc_array.php
Sorcerer: 五条悟
Sorcerer: 夏油傑

Both『//』and『#』are single-line comments with the same behavior, but『//』is common in PHP codebases. Inline comments are useful for briefly supplementing the intent of adjacent code. For multi-line explanations or temporarily disabling code, use『/* ... */』.Block comments cannot be nested.Writing『/* /* ... */ */』ends the comment at the inner『*/』.

PHPDoc comments (block comments beginning with『/**』) are a mechanism for recording type information and descriptions in a format that IDEs can recognize. Use『@param』for argument types and descriptions,『@return』for return value type and description, and『@var』for property types.Information that cannot be expressed with type hints—such as array element types (e.g.,『array<string>』)—can be supplemented with PHPDoc.Combining type hints with PHPDoc improves IDE autocompletion accuracy and enables bug detection by static analysis tools such as PHPStan and Psalm.

Comments are most useful for maintenance when they explain "why" rather than "what". For type declarations, see『Function Definition』. For exception handling, see『try / catch / finally』.