PHPDocコメント まとめ

はじめに

この記事はプログラミング初学者による備忘録用の記事であり、また、少しでも他の初学者のお役に立てればと思い書いています。

今回は、Laravelを使う際にコメントを書くことが多々あり、いくつかの記法の中でも特に情報量が多いドキュメントコメントの書き方(PHPDoc)について、備忘録としてまとめておきたいと思います。

間違いなどがございましたら、ご指摘のほどよろしくお願い致します。

ドキュメントコメントとは(PHPDoc)

Docブロックはコードに詳細な情報を記述することができる、特別な種類のコメント文です。
このコメントは機能についての理解を促進させる情報を提供するために利用されます。 DocコメントをもとにIDEが自動補完の手がかりとしたり、phpDocumentorがAPIドキュメントを生成します。
引用phpDocumentor

コメント対象となる要素

対象となる要素一覧
名前空間 / namespace
require(_once)
include(_once)
クラス / class
インターフェイス / interface
トレイト / trait
関数 / function (メソッドを含む)
プロパティ / property
定数 / constant
変数(ローカルおよびグローバル) / variables, both local and global scope.

メソッドの直前で/** */を書き、その中に関数・クラス・メソッド等に関するコメントを記述します。

PHPDocの書式でコメントを記述するメリット

チームの他の開発者や、自分のコードを読み返すときの説明として有用であり、そして、PHPDocを活用したツールにて利用できるメリットがあります。

ツール例
・PHPStan
・PhpStorm
など、静的解析の精度向上に貢献でき、バグの発生を抑制することができます。

PHPDocの記述内容は大きく3つに分かれている

コメントの内容は3つに分かれていて
(1)クラスやメソッドに関する要約
(2)クラスやメソッドに関する具体的な説明文
(3)タグによって構造化されたメタデータを記述
となっています。

下記にて、基本的な書き方を記しておきます。

PHPDocの例

/**
 * 要約  (1)
 * 各要素に関する具体的な説明  (2)
 *
 * @タグ 名前・引数・返り値などを指定  (3)
 */

クラスやメソッドに関するコメント

PHPDocでは、クラスやメソッド、プロパティに関するコメントを記述する場合、関連する「引数」「返り値」の情報を必ず記述します。

引数や返り値を記述するためのタグが存在しており、下記のような役割を果たします。
・@param -> 引数の情報を記述する
・@return -> 返り値の情報を記述する
・@var -> 変数、オブジェクトのプロパティの情報を記述する

タグは定義に型を含み、これらの型は様々な種類のデータを表現できます。
注意点:
PHP公式の型の定義とは少し異なります。

上記3つのタグの特徴をもう少し詳細に述べると

@paramとは
引数に対して使用され、@param \Namespace\Sample $sampleといったように、引数の名前空間を指定した後に続けて引数として存在する変数名を指定します。

@returnとは
返り値に対して使用され、@return intのように、@ returnタグでは関数またはメソッドの返り値と機能を文書化することができます。また、複数行の説明を持つことができ、明示的な区切りを必要としません。基本的には、@ returnタグで返り値を明確にしておきます。
しかし、下記2点の場合は@ returnタグを必要としません。

@returnタグを必要としないケース

・コンストラクタ ： @return タグを書かなくてもよく、暗黙的に @return selfになります。
・関数またはメソッドに return する値がない ： @return タグを書かなくてもよく、暗黙的に @return void になります。
引用phpDocumentor @return

注意点:

・このタグは複数回書いてはいけません
・書くことができるのは構造要素のうち、関数またはメソッドに限ります。
・Type が複数の型からなるとき、必ず複数の型を縦棒/vertical bar sign | で区切って書かなければいけません。
引用phpDocumentor @return

また、@returnではキーワードを定義することができ、「キーワード」では型の目的を定義します。

キーワード(型)一覧

型名	説明
string	この型が適用される要素はバイナリ文字の文字列です。
int	この型が適用される要素は整数です。
bool	この型が適用される要素は true または false です。
float or double	この型が適用される要素は連続量または実数です。
object	この型が適用される要素はクラスを特定しないインスタンスです。
mixed	この型が適用される要素は任意の型の値です。それはコンパイル時に型が使用されません。
array	この型が適用される要素は値の配列です。
resource	この型が適用される要素はリソース値で、それぞれの定義は http://www.php.net/manual/language.types.resource.php にあります。
void	この型は関数またはメソッドの返り値の定義にのみ利用されます。 基本的な定義としてはこの要素は値を含まず、ユーザーは返り値に依存してはいけないことを意味します。
null	明示的に NULL 値を含む可能性のある状況で使用されることが void との大きな差異です。この型は一般に別の型に関連して、何の値も返されない可能性がある場合に使用されます。
callable	この型が適用されるのは函数呼び出しへのポインタです。 PHPマニュアル http://php.net/manual/language.pseudo-types.php で定義される、callbackのどのようなタイプでも良いです。
false or true	この型が適用される要素はtrueまたはfalse値です。この要素からほかの値は返されません。この型は一般に別の型に関連して、true/falseと別の型のインスタンスが返される可能性がある場合に使用されます。

複数存在するarrayの記述方法
公式ドキュメントでは3つの形式が紹介されているが、1つの形式に対して多くのIDEはおそらくまだこの形式をサポートしていないと書かれているなど、不明瞭な点があるので内容について定義しない形式である@return arrayを採用する。

@paramと@returnの例

/**
 * ユーザーがいいね済みかどうかを判定
 * where()で記事をいいねしたユーザーの中に、引数として渡された$userがいるかどうかを判定
 *
 * @param \App\Models\User $user
 * @return bool
 */
 public function isLikedBy(?User $user): bool
 {
  return $user ? (bool)$this->likes->where('id', $user->id)->count() : false;
 }

@varとは
書き方としては@var [“型を指定”] [変数名] [説明文]という形でコメントを記述して
プロパティの値のデータ型を定義することができ、必ず文書化する要素名を含む必要があります。
例外として、プロパティ宣言で1つのプロパティに言及する場合、プロパティの名前を省略することができます。

@varの例

class Sample
{
  /** @var string|null ここに説明を書きます */
  protected $description = null;
}

//複数の場合
class Sample
{
  /**
   * @var string $name        ここに説明を書きます
   * @var string $description ここに説明を書きます
   */
  protected $name, $description;
}

まとめ

上記で挙げた3つのタグを使い、コメントで引数や返り値の説明をすることで、他の開発者がコードを読んだ時に、何を渡し何が返ってくるのかが明確になり、コード変更等でのエラー発生率を下げることができます。

おわりに

コメントは、他の開発者と意思疎通を図る手段の1つであり、また、未来の自分に対してコメントを残すことで各コードを修正しやすくするので、常日頃から分かりやすいコメントを残すよう心がけたいと思います。

参考文献

PHPDoc リファレンス