PHPDoc とタイプヒントの違いと活用方法

Laravel のコードを書いている際
「PHPDoc とタイプヒントってどんな違いがあるの？」
「両方書く意味あるの？」
など、疑問が湧いてきたのでせっかくの機会に調べることにしました。

主な利用目的

PHPDoc

このコメントは機能についての理解を促進させる情報を提供するために利用されます。 DocコメントをもとにIDEが自動補完の手がかりとしたり、phpDocumentorがAPIドキュメントを生成します。

引用

PHPDoc は名前の通りドキュメント向けです。 phpDocmentator がAPIドキュメントを作成してくれたりとドキュメント利用を前提としていることから拡張ツールなどもドキュメント生成などに対応してくれます。

タイプヒント

こちらもコーディングの際の手助けにはなりますが、PHPDoc と違う部分は実行した際型が違うオブジェクトが代入された場合 TypeError を発生させます(PHP8.0 から対応。別バージョンだとエラーが発生しないらしい)。利用目的としては「型の厳格化」「実行環境テストなどでの未然事故防止」となりそうです。

両方書く必要あるの？

結論、私個人としては両方書くことをお勧めします。理由としては以下のとおりです。

• 実行環境エラーによるバグ認知のため、タイプヒントは欲しい
• 引数等に対する補足説明を書くケースを考えると、PHPDoc は欲しい

私自身は Generator などを利用していませんが、これらを利用せずテキストエディタの表示のみの利用でも有意義です。個人開発レベルでもメソッドの概要把握などを考慮すると生産性が上がるため、どのレベルのプロダクトにおいても利用価値があるものだと感じています。

なお、以下のように「タイプヒントで型定義、PHPDocで型定義を削除し重複を防ぐ」のような処置を検討しましたが、PHPDoc には @param <type_name> <argument_name> <description> のような引数が決まっていそうなので不可能でした。

/**
 * NG
 *
 * @param $txt This is a sample text.
 */
public function sample2(string $txt)
{
  return $txt;
}

/**
 * OK
 *
 * @param string $txt This is a sample text.
 */
public function sample3(string $txt)
{
  return $txt;
}

参考画像

最後に

それぞれの機能の由来をよくよく考えてみれば当たり前のことですが、基礎の積み重ねが技術力へとつながっていくので定期的に疑問視した内容等を投稿できればと思います。

ここまで読んでいただきありがとうございました！補足、認識違い等ございましたらコメントしていただけると幸いです。いいね・フォローも励みになるのでよろしくお願いします！