コメント（// # /* */ と PHPDoc）

// 一行コメント（// 記法）
// この行はコメントです

# 一行コメント（# 記法）
# この行もコメントです

$value = 100; // 行末コメントも書けます

/* ブロックコメント */
/*
  複数行にわたるコメントです。
  長い説明を書く場合に使います。
*/

/**
 * PHPDocコメントです。
 * 関数・クラス・プロパティの直前に書きます。
 *
 * @param 型名 $引数名 引数の説明
 * @return 型名 戻り値の説明
 * @var 型名 プロパティの説明
 */

記法	種類	概要
//	一行コメント	『//』から行末までがコメントになります。最もよく使われる記法です。
#	一行コメント	『#』から行末までがコメントになります。シェルスクリプト風の記法で、機能は『//』と同じです。
/* ... */	ブロックコメント	『/*』から『*/』までの範囲がコメントになります。複数行にわたる説明や、コードの一時的な無効化に使います。
/** ... */	PHPDocコメント	『/**』で始まるブロックコメントです。IDEやドキュメント生成ツールが認識できる形式で、型情報や説明を記録します。

タグ	使用場所	概要
@param	関数・メソッド	引数の型と説明を記述します。書式は『@param 型名 $引数名 説明』です。
@return	関数・メソッド	戻り値の型と説明を記述します。書式は『@return 型名 説明』です。
@var	クラスプロパティ	プロパティの型を記述します。書式は『@var 型名 説明』です。
@throws	関数・メソッド	スローする可能性のある例外クラスを記述します。
@param array<型>	関数・メソッド	配列の要素の型を明示します。例：『@param array<string>』は文字列の配列です。

PHP 7以降では関数の引数や戻り値に型宣言（型ヒント）を書けます。型ヒントは実行時に型チェックが行われますが、PHPDocはあくまで注釈であり実行時には影響しません。両者は次のように使い分けます。

場面	推奨する記法
引数・戻り値の型を強制したい	型ヒント（実行時チェックあり）
配列の要素の型を示したい	PHPDoc（例：『@param array<string>』）。型ヒントでは『array』までしか書けないためです。
プロパティの型を示したい（PHP 7.3以前）	PHPDoc（『@var 型名』）
IDEの補完・静的解析を強化したい	型ヒントとPHPDocを併用する。

comment_basic.php

<?php
// 一行コメントと行末コメントの基本的な使い方です
// 呪術廻戦の術師情報を変数に格納します

$sorcererName = "五条悟"; // 術師の名前
$grade = "特級"; // 術師等級
$cursedTechnique = "無下限呪術"; // 術式名

# # 記法の一行コメントです。// と同じ意味です
# 変数の内容を表示します

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

/*
  ブロックコメントは複数行にわたる説明や、
  一時的にコードを無効化したい場合に使います。
  以下のコードは現在無効化されています。

  echo "このコードは実行されません。\n";
*/

実行すると次のように出力されます。

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

comment_phpdoc_function.php

<?php
/**
 * 術師の名前と等級から紹介文を生成します。
 *
 * @param string $name  術師の名前
 * @param string $grade 術師等級（特級・1級・2級など）
 * @param int    $power 呪力量（0以上の整数）
 * @return string 整形された紹介文
 */
function formatSorcererProfile(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "術師）/ 呪力量: " . $power;
}

// PHPDocの @param/@return を書くと、IDEが引数の型と説明を補完してくれます
echo formatSorcererProfile("伏黒恵", "1級", 850) . "\n";
echo formatSorcererProfile("釘崎野薔薇", "1級", 720) . "\n";
echo formatSorcererProfile("虎杖悠仁", "特級", 9800) . "\n";

実行すると次のように出力されます。

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

comment_phpdoc_class.php

<?php
/**
 * 呪術師を表すクラスです。
 * 名前・等級・術式をまとめて管理します。
 */
class Sorcerer {

	/**
	 * @var string 術師の名前
	 */
	public string $name;

	/**
	 * @var string 術師等級
	 */
	public string $grade;

	/**
	 * @var array<string> 使用できる術式の一覧
	 */
	public array $techniques;

	/**
	 * コンストラクターです。
	 *
	 * @param string        $name       術師の名前
	 * @param string        $grade      術師等級
	 * @param array<string> $techniques 術式の一覧
	 */
	public function __construct(string $name, string $grade, array $techniques) {
		$this->name = $name;
		$this->grade = $grade;
		$this->techniques = $techniques;
	}

	/**
	 * 術師の情報を整形して返します。
	 *
	 * @return 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";

実行すると次のように出力されます。

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

comment_phpdoc_throws.php

<?php
/**
 * 指定した等級の術師を検索します。
 * 等級が無効な場合は例外をスローします。
 *
 * @param  array<string, string> $sorcerers 術師名 => 等級の連想配列
 * @param  string                $targetGrade 検索する等級
 * @return array<string> 該当する術師名の配列
 * @throws \InvalidArgumentException 等級が空文字列の場合
 */
function findByGrade(array $sorcerers, string $targetGrade): array {
	// 空文字列の等級は無効なので例外をスローします
	if ($targetGrade === "") {
		throw new \InvalidArgumentException("等級を指定してください。");
	}

	$result = [];
	foreach ($sorcerers as $name => $grade) {
		if ($grade === $targetGrade) {
			$result[] = $name; // 一致した術師名を結果配列に追加します
		}
	}
	return $result;
}

// 術師名 => 等級の連想配列です
$sorcerers = [
	"五条悟" => "特級",
	"夏油傑" => "特級",
	"伏黒恵" => "1級",
	"釘崎野薔薇" => "1級",
	"虎杖悠仁" => "特級",
];

$tokkyuList = findByGrade($sorcerers, "特級");
echo "特級術師: " . implode("、", $tokkyuList) . "\n";

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

実行すると次のように出力されます。

php comment_phpdoc_throws.php
特級術師: 五条悟、夏油傑、虎杖悠仁
1級術師: 伏黒恵、釘崎野薔薇

ブロックコメントを入れ子にする

『/* ... */』の入れ子はできません。内側の『*/』でコメントが終了してしまい、その後のコードが構文エラーになります。

ng_comment_nested.php

<?php
/*
  /* 入れ子のブロックコメント */
  ここはコメントのつもりだが、内側の */ でコメントが終わる
*/
echo "五条悟（特級）: 無下限呪術\n";

実行すると次のように出力されます。

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

ブロックコメントを複数重ねたい場合は、一行コメント（//）に変えるか、入れ子を避けてひとつのブロックにまとめます。

ok_comment_nested.php

<?php
/*
  // 一行コメントはブロックコメント内に書ける
  ここはブロックコメントの中
*/
echo "五条悟（特級）: 無下限呪術\n";

実行すると次のように出力されます。

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

PHPDocコメントの @param の順番を引数と揃えない

PHPDocの @param は実際の引数の順番と一致させる必要はありませんが、順番がずれると読み手が混乱しやすく、IDEや静的解析ツールが誤った補完・警告を出すことがあります。

ng_phpdoc_order.php

<?php
/**
 * @param int    $power 呪力量
 * @param string $grade 術師等級
 * @param string $name  術師の名前
 * @return string
 */
function describeSorcerer(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "）/ 呪力量: " . $power;
}

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

実行すると次のように出力されます。

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

PHPDocの @param は引数の順番に揃えて書きます。

ok_phpdoc_order.php

<?php
/**
 * @param string $name  術師の名前
 * @param string $grade 術師等級
 * @param int    $power 呪力量
 * @return string
 */
function describeSorcerer(string $name, string $grade, int $power): string {
	return $name . "（" . $grade . "）/ 呪力量: " . $power;
}

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

実行すると次のように出力されます。

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

PHPDocで配列の要素型を書かずに array だけ書く

引数・戻り値の型ヒントで array と書いた場合、IDEや静的解析ツールは配列の中に何が入っているかを把握できません。要素の型が決まっている場合は PHPDoc で補足します。

ng_phpdoc_array.php

<?php
/**
 * @param array $names 術師名の配列
 * @return array 結果の配列
 */
function listSorcerers(array $names): array {
	return array_map(fn($n) => "術師: " . $n, $names);
}

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

実行すると次のように出力されます。

php ng_phpdoc_array.php
術師: 五条悟
術師: 夏油傑

array<string> のように要素の型を PHPDoc で明示するとIDEの補完精度が上がります。

ok_phpdoc_array.php

<?php
/**
 * @param array<string> $names 術師名の配列
 * @return array<string> 結果の配列
 */
function listSorcerers(array $names): array {
	return array_map(fn($n) => "術師: " . $n, $names);
}

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

実行すると次のように出力されます。

php ok_phpdoc_array.php
術師: 五条悟
術師: 夏油傑

『//』と『#』はどちらも一行コメントで機能は同じですが、PHPのコードベースでは『//』が一般的です。行末コメントはコードの意図を短く補足したい場合に活用します。複数行にわたる説明や一時的なコードの無効化には『/* ... */』を使います。ブロックコメントを入れ子にすることはできません。『/* /* ... */ */』のように入れ子にした場合、内側の『*/』でコメントが終了してしまいます。

PHPDocコメント（『/**』で始まるブロックコメント）は、IDEが認識できる形式で型情報と説明を記録する仕組みです。『@param』で引数の型と説明、『@return』で戻り値の型と説明、『@var』でプロパティの型を記述します。型ヒントで表現できない情報、たとえば配列の要素型（『array<string>』など）はPHPDocで補足します。型ヒントとPHPDocを併用することでIDEの補完精度が上がり、PHPStanやPsalmなどの静的解析ツールによるバグ検出も機能します。

コメントはコードが「何をしているか」よりも「なぜそうしているか」を書くと保守性が高まります。型宣言については『関数定義』を、例外処理については『try / catch / finally』を参照してください。