タイトル: コメント
SEOタイトル: PHP コメント完全ガイド (// / # / /* */ / PHPDoc)
| この記事の要点 |
- PHP のコメントは
// 1 行 / # 1 行 / /* 複数行 */ / /** PHPDoc */ の 4 種 - PHPDoc
/** ... */ は IDE 補完・静的解析 (PHPStan/Psalm) の型情報源として活躍 - 主要タグ:
@param / @return / @throws / @var / @deprecated / @see / @since - PSR-5 が PHPDoc の仕様 (Draft)、phpDocumentor でドキュメント自動生成
- アンチパターン: 「コメントで挙動を説明する」より「関数名 / 変数名で表現」。コメントは"why"を書く
|
4 種類のコメント構文
PHPDoc の主要タグ
| タグ | 用途 | 例 |
|---|
@param | 引数の型と説明 | @param int $id ユーザー ID |
@return | 戻り値の型と説明 | @return User|null |
@throws | 投げる例外 | @throws NotFoundException |
@var | プロパティ / 変数の型 | @var array |
@deprecated | 非推奨マーク | @deprecated 1.5 use bar() |
@see | 関連参照 | @see User::find() |
@since | 追加バージョン | @since 2.0.0 |
@author | 作成者 | @author Taro |
@link | 外部参照 URL | @link https://example.com/docs |
@template | ジェネリクス (Psalm/PHPStan) | @template T of Model |
@internal | 内部使用専用 | — |
関数コメントの実例
クラス / プロパティコメント
ID → User のキャッシュ
*/
private array $cache = [];
/**
* @var \PDO データベース接続
*/
private \PDO $pdo;
/** @var int キャッシュ有効秒数 */
private const TTL = 300;
}
静的解析ツールとの連携
| ツール | 役割 | PHPDoc 活用 |
|---|
| PHPStan | 静的解析・型チェック | ジェネリクス / 配列 shape 推論 |
| Psalm | 静的解析・型チェック | 厳密な型推論 |
| PhpStorm / VS Code | IDE 補完 | 引数 / 戻り値ヒント |
| phpDocumentor | API ドキュメント生成 | HTML 出力 |
| Doctum / Sami | ドキュメント生成 | Symfony / Laravel 系で人気 |
PHPDoc 専用の型表現
$names キー int、値 string の配列
* @param array $scores キー string、値 int
* @param list $tags 0 始まり連番の配列
* @param array{name: string, age: int} $user shape 指定
* @param 'asc'|'desc' $order リテラル型 (PHP 8.1+ Enum 代替)
* @param int<1, 100> $page 範囲指定
* @param non-empty-string $title 空文字不可
* @return Generator 戻り値の Iterator 中身
*/
function search(array $names, array $scores, array $tags, array $user, string $order, int $page, string $title): \Generator {
// ...
}
コメントのアンチパターン
= 0) {
$order->markAsPaid();
}
// ✅ TODO / FIXME / XXX (IDE で抽出可能)
// TODO: PHP 8.2 で readonly class に置き換え
// FIXME: タイムゾーン考慮漏れ
他言語との対比
| 言語 | 1 行 | 複数行 | ドキュメント |
|---|
| PHP | // # | /* */ | PHPDoc /** */ |
| JavaScript | // | /* */ | JSDoc /** */ |
| Java | // | /* */ | JavaDoc /** */ |
| Python | # | ''' ''' | docstring + Sphinx |
| Ruby | # | =begin =end | YARD / RDoc |
| Go | // | /* */ | godoc (コメント自体) |
FAQ
Q: // と #、どちらを使うべき？
A: PSR-12 では特に規定なし。チーム慣習に従う。一般的に // が多数派です。
Q: PHPDoc は書かないとダメ？
A: 型宣言 (PHP 7.0+) で補えれば省略可。ただし配列の中身 / ジェネリクス / 例外は型宣言で表現できないため PHPDoc が役立ちます。
Q: コメントは何語で書く？
A: チーム共通言語で。OSS は英語推奨。日本国内クローズドなら日本語 OK。混在は避ける。
