PHPコメントの書き方（PHPDoc）

みなさんはLaravelを使ってPHPのソースコードを書くとき、どのようにコメントを書くでしょうか？覚書きに程度に使用はしていませんか？

プログラミングにおけるコメントの書き方はとても重要です。

きちんとしたコメントの書き方をすれば、一見複雑な処理でも処理内容がすぐに分かるようになります。

そのため、厳密にコメントを記載することをルールとしている企業もあります。

今回はPHPにおけるコメントの書き方（主にPHPDoc）についてエントリーします。

 

Index

1. ドキュメントコメント（DocComment）の書き方

PHPでのコメントの書き方には4種類あります。

• 一行コメント
• シェバン（shebang）
• 複数行コメント
• ドキュメントコメント（DocCommnet）

この内、PHPでのクラスやメソッドの直前にはドキュメントコメントを記述します。

これは /** */ でくくられるコメントです。

開始の ** は必ず二つなので気をつけてください。終了の * はひとつで十分です。

/**
* DocComment
*/

/**
* 複数行書くこともできる
*
* 慣習として、全ての行に * を書く
*/


/** これもドキュメントコメント */

 

実際に僕が書いている例だと以下のような感じになります。

 
逆に、以下のようなコメントはドキュメントコメントではありません。複数行コメントになります。

/*
* これはドキュメントコメントではない
* ドキュメントコメントと紛しいので、この形式でコメントを書くことはオススメしません
*/

 

複数行コメントは、ドキュメントコメントの書き方と紛らわしいのでおススメしません。

もしPHPで複数行のコメントを書く場合は、以下のような記述をすると、ドキュメントコメントと混同されません。

// DocCommentではない場所で長文を書きたいとき
// こう書いた方が混同されないのでマシ

 

２．PHPDocの書き方

PHPでは、ファイルの先頭やクラスやメソッドの直前に、このドキュメントコメントの書き方(PHPDoc)をします。

PHPのファイルの説明、関数・クラス・メソッドの説明などは、このPHPDocを使ってコメントします。

PHPDocはおおまかに四つのセクションに分かれています。

ファイル全体の説明をする時はファイルの先頭にPHPDDocを記述します。その場合、１番から３番を記述することが多いです。

一方、クラスやメソッドの説明には４番は必須になります。

制作者の名前や参考資料、引数や返り値といった情報は "＠" ではじまる特殊な記法を使って記述します。

これを "タグ" と呼びます。（※アノテーションとも呼んだりします）

例えば、ファイル説明をする場合は以下のように記述します。

/**
* １行で処理の内容を記述
*
* 1行空けてもう少し詳しく記述することができる
* 複数行記述ができて、不要なら省略もできる
*
* @author 名前 <メールアドレス>
*  
*/

 

その一方、クラスやメソッドを説明する場合は引数や返り値のタグは必須になります。１番と４番のみで記述されることが多いです。以下のように記述します。

/**
* １行で処理の内容を記述
*
* @param int $example    第一引数の説明文をここに入れます。
* @param strng $example2 第二引数の説明
*/

 

３．PHPDocの書き方（実例：ファイル）

そのファイル全体の説明をする場合は、「要約」と「説明」に加えてファイルに関してのタグを記述します。

ファイルに関してのタグは以下があります。

「ファイルに関してのタグ」を開く

ファイルに関してのタグはたくさん種類がありますが、必須のタグとかはありません。

ただし、以下の３つのタグがよく使われています。

• ファイルのバージョンはいくつなのか？
• 誰が書いたのか？
• 関連する情報のあるリンク

以下は実例です。

/**
 * laravelデフォルトページ用コントローラーのファイル
 * 
 * このファイルではlaravelのデフォルトページで行う処理 
 * に関するコントローラーを書いています。 
 * 
 * @version 1.0 
 * @author Honjo 
 * @link https://laraweb.net 
 * 
 */

 

４．PHPDocの書き方（実例：クラス・メソッド）

クラスやメソッドの説明を記述する場合は「引数」「返り値」の情報を記述します。

オブジェクトのプロパティ情報といった場合は「変数」の情報を記述します。

これらの情報もタグ形式で記述します。

• @var [型] 説明
• @param [型] 変数名 説明
• @return [型] 説明

なお、クラスやメソッドの説明ではこれらのタグは必須になります。

以下、実例です。

/**
*  マスアサインメントの保護を外す
*   
* @var array プロパティ
*/
protected $fillable = [ 'name', 'email', 'password', ];
：

/**
* エリアチェック
*
* @param string $area_code 地域コード(入力値)
* @return array 地域コード、地域名
*/
private function check_area($area_code)
{
：

 

クラスやメソッドに記述するコメントでは 要約とタグ（引数+返り値もしくは変数）のセットで記述することが多いです。

特に引数と返り値を説明するタグは必須です。

その理由はパラメータや、戻り値の型を記述することで、そのメソッド（関数）を利用しようと考えた時に、「何を渡せばよいか？」「何が返ってくるのか？」が明確になるからです。

バグもこれで抑制できるようになります。

 

５. 処理の挙動

クラスやメソッドはPHPDocで記述しますが、その中に記述している処理の挙動は一行コメントで記述します。

PHPでの一行コメントは「//」もしくは「#」でコメントの始まりを指定します。

どちらの文字も同じ機能ですが、混在すると混乱の原因となるので、使用するときはどちらかに統一します。

ほとんどの人は「//」で記述しています。

/**
* 管理機能_アカウント検索
*  
* @param array $input 検索条件
* @return array 検索結果
*/
public static function search_account($input)
{
   //検索実行
   $query = static::create_search_query($input);
   
   //ページ情報
   $page_info = static::create_page_info($query, $input, self::ROWS_PER_PAGE);

   //ページネーション作成
   $pagination = static::create_pagination($page_info['count'], self::ROWS_PER_PAGE);
：

 

６. ブロックごとの処理

クラスやメソッドの中に記述しているコードが長くなってくることがあります。（※一般的にはこれはよくないコードとされます）

長いコードになってくると、どこからなんの処理をしているかがわかりづらくなってしまいます。

それを防ぐために、一行コメントとは別に下のようなコメントをするとわかりやすいです。

複数行コメントはドキュメントコメントの記述と混在するのでおススメはしません。

//****************************************
//     入力処理
//****************************************
if ($passwd == $_POST['passwd']) { 
：

 
以上です。

 

 

-周辺知識