過去バージョン

4 種類のコメント構文

<?php
// 1 行コメント (C / Java スタイル)
echo 'hello';    // 末尾コメント

# 1 行コメント (Bash / Perl スタイル) - PHP 独自
echo 'hi';       # こちらも有効

/*
  複数行コメント
  ブロックコメント
*/

/**
 * PHPDoc 形式（IDE / 解析ツール対応）
 *
 * @param string $name 名前
 * @return string 挨拶文
 */
function greet(string $name): string {
    return "Hello, $name";
}

PHPDoc の主要タグ

関数コメントの実例

<?php
/**
 * ユーザーを ID で検索する
 *
 * 削除済ユーザーは含まれない。
 * キャッシュは 5 分間有効。
 *
 * @param int  $id        ユーザー ID（1 以上）
 * @param bool $withTrash 削除済も含めるか
 * @return User|null 見つからなければ null
 * @throws InvalidArgumentException $id が 0 以下のとき
 * @see UserRepository::findByEmail() メールで検索
 * @since 1.2.0
 */
public function find(int $id, bool $withTrash = false): ?User {
    if ($id <= 0) {
        throw new InvalidArgumentException('id must be positive');
    }
    // ...
}

クラス / プロパティコメント

<?php
/**
 * ユーザーリポジトリ
 *
 * DB から User Entity を取得する。
 *
 * @package App\Repositories
 * @author  Taro Yamada
 */
class UserRepository
{
    /**
     * @var array<int, User> ID → User のキャッシュ
     */
    private array $cache = [];

    /**
     * @var \PDO データベース接続
     */
    private \PDO $pdo;

    /** @var int キャッシュ有効秒数 */
    private const TTL = 300;
}

静的解析ツールとの連携

PHPDoc 専用の型表現

<?php
/**
 * PHPDoc では PHP の型システムを超えた表現が可能
 *
 * @param array<int, string>      $names    キー int、値 string の配列
 * @param array<string, int>      $scores   キー string、値 int
 * @param list<string>            $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<int, User>             戻り値の Iterator 中身
 */
function search(array $names, array $scores, array $tags, array $user, string $order, int $page, string $title): \Generator {
    // ...
}

コメントのアンチパターン

<?php
// ❌ コードを日本語で繰り返すだけ
$i = 0;        // i に 0 を代入
$i++;          // i をインクリメント

// ❌ 嘘コメント（リファクタで挙動が変わってもコメントが残る）
// ユーザーをメールで検索
function findByName(string $name) { /* メールではなく名前で検索している */ }

// ❌ コメントアウトで残されたデッドコード
// $oldLogic = ...;
// if ($oldLogic) { ... }

// ✅ Why を書く（なぜそうしたか）
// 業務要件: 0 円商品も「購入済」扱いにする (#1234)
if ($price >= 0) {
    $order->markAsPaid();
}

// ✅ TODO / FIXME / XXX (IDE で抽出可能)
// TODO: PHP 8.2 で readonly class に置き換え
// FIXME: タイムゾーン考慮漏れ

他言語との対比

FAQ

Q: // と #、どちらを使うべき？
A: PSR-12 では特に規定なし。チーム慣習に従う。一般的に // が多数派です。

Q: PHPDoc は書かないとダメ？
A: 型宣言 (PHP 7.0+) で補えれば省略可。ただし配列の中身 / ジェネリクス / 例外は型宣言で表現できないため PHPDoc が役立ちます。

Q: コメントは何語で書く？
A: チーム共通言語で。OSS は英語推奨。日本国内クローズドなら日本語 OK。混在は避ける。