PHPコメントの書き方(PHPDoc)

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

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

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

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

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

「コメント」と「コメントアウト」は意味が少し違います。
コメントアウトはソースコードをコメントすることで、プログラムを無効化することを指します。

 

Index

1. ドキュメントコメント(DocComment)の書き方

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

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

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

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

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


/**
* DocComment
*/

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


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

 

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


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

 

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

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


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

 

2.PHPDocの書き方

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

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

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

1.要約(処理の内容を一行で記述)
2.説明(処理の内容をさらに詳しく説明)
3.タグ(名前・参考資料など)
4.タグ(引数・返り値)

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

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

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

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

PHPDocリファレンスでは「要約」「説明文」「タグ」の三つのセクションとして説明されています。
phpDocumentor - 基本文法 - セクション

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


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

 

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


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

 

3.PHPDocの書き方(実例:ファイル)

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

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

タグ名 説明
@access 構文:@access アクセスレベル
実例:@access public
@author 構文:@author 名前 メールアドレス
実例:@author Honjo honjo@example.com
@copyright @copyright 会社名 All Rights Reserved
@category @category カテゴリー(処理系)
※このタグは今後、廃止が予定されています。使用が推奨されていません。
@link @link 参考資料のURL
@see 構文:@see 関連(呼び出したり)する関数
実例:@see MessageApi::paramCheck
@throws 構文:@throws 可能性のある例外を記述す
実例:@throws NotFoundException メッセージがない場合は404エラーを返す
@todo 構文:@todo TODO事項
実例:@todo パフォーマンス改善の余地あり

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

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

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

以下は実例です。


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

 

4.PHPDocの書き方(実例:クラス・メソッド)

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

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

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

  • @var [型] 説明
  • @param [型] 変数名 説明
  • @return [型] 説明
1.@var は変数、オブジェクトのプロパティ情報
2.@param が引数の情報
3.@return が返り値の情報

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

以下、実例です。


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

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

 

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

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

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

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

 

5. 処理の挙動

クラスやメソッドは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);
:

 

6. ブロックごとの処理

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

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

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

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


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

 

以上です。

本庄マサノリ

仕事で Laravel を使っています。気づいたことや新しい発見など情報を発信していきます。問い合わせはこちら

>> Twitter をフォローする

 

-周辺知識

おすすめ記事

動画で学習するなら ドットインストール、Schoo、Udemyのどれがいい?

フリーランスを目指すなら フリーランスエージェントTOP3