コメントは、プログラミングの際に処理の役割や説明をする上で、大変重要な役割を持っています。
PHPではさまざまな方法でコメントをすることができます。
この記事では、
- 「//」を使用したコメントの付け方
- 「/* */」を使用したコメントの付け方
- 「#」を使用したコメントの付け方
- コメントの応用的な使い方
- HTML含む場合のコメント方法
- コメントの注意点
などのコメントの基本的な内容から、応用的な使い方について解説します。
コメントはコーディングする上で必ずしも記載が必要なものではありませんが、重要な要素の1つであることに変わりありません。
ここではPHPのコメントについて詳しく解説していきます！
コメントとは？
ここでは、コメントについておさらいしてみましょう。
用語検索サービスである「コトバンク」では、以下のように説明しています。
「プログラムの中に書き込まれた、処理の記述以外の説明文のことをコメントという。」
コメントは、作成者の覚書きに使用することが多い印象ですが、ファイル名やプログラムのバージョン、クラス名、関数名を記述したり、不具合を修正するときなど、さまざまな用途でよく使用されます。
一見複雑な処理でも、コメントを確認すれば処理内容が分かるように、各処理については、厳密にコメントを記載することをルールとしている企業もあります。
また、プログラムを修正するときに、元々記述している処理を消してしまうのではなく、将来元に戻す可能性のあるときに、処理をまるごとコメントして無効化するときにも使われます。
ちなみにコメントとコメントアウトは混同しやすいですが、コメントアウトはソースコードをコメントすることで、プログラムを無効化することを指します。
PHPのコメント3つのパターン
ここでは、PHPでコメントするさまざまな方法について紹介します。
行頭に「//」を付ける
「//」は、行頭から行末まで１行でコメントする場合によく使用します。
一般的によく使用するタイプのコメントです。
<?php $str = 'コメントのテストです'; //ここからコメント //結果を出力します。 echo $str; ?>
コメント範囲を「/* */」で囲む
「/* */」は複数行コメントする場合によく使います。
間に改行を入れることも可能です。
<?php /* 2017/07/01追記 ここでは、連想配列に値を設定し、 print_rで配列の中身を出力します。 */ $fruits = [0=>'apple', 1=>'orange', 2=>'melon', 3=>'banana', 4=>'pineapple']; /* 結果を出力 */ print_r($fruits); /* このように、 改行を挟むこともできます。 */ ?>
「/* */」の形式はコメントをネストすると最後の「*/」が無いと判断されて、エラーとなりますので注意しましょう。
<?php /* /*結果を出力 */ echo 'これはエラーになります'; */ ?>
行頭に「#」を付ける
「#」は、「//」と同じく行頭から行末まで1行でコメントするときに使用します。
シェルやCSVファイルのコメントでよく使用される形式です。
<?php $str = 'コメントのテストです'; #ここからコメント #結果を出力します。 echo $str; ?>
HTML含む場合のコメント
PHPのソースをまとめてコメントアウト
HTMLのコメントを使用して、PHPのソースをまとめてコメントすることもできます。
以下の例では'コメントのテスト1'の箇所のPHPのソースがまるごとHTMLのコメントで囲まれています。
<html> <head> <title>PHP入門</title> </head> <body> <!-- <?php echo 'コメントのテスト1'; ?> --> <?php echo 'コメントのテスト2'; ?> </body> </html>
実行結果：
コメントのテスト2
PHPのコメントアウトを使用する
以下のような方法でもPHPのソースを丸ごとコメントすることができます。
<html> <head> <title>PHP入門</title> </head> <body> <?php /* $text = 'コメント'; echo $text; <?php echo 'ここもコメントされる'; ?> */ ?> </body> </html>
コメントの注意点
コメントは多用すると、タグが全て閉じられなかったり、コメントがされない場合がありますので注意しましょう。
以下のようなコメントが入れ子になっている場合はうまくコメントされません。
/* echo 'コメントアウト'; echo 'コメントアウト';*/ echo 'コメントアウトされていない';*/
また、phpのタグの前で/**/を使用してコメントしても、コメントされませんので注意しましょう。
/* <?php echo 'コメントアウトされていない';*/ ?> */
コメントの応用的な使い方
プロジェクトによっては、コメントの付け方も厳密に決められていることがあります。
コメントは後から処理を見直したり、他の人がソースを読んだときに、ひと目で処理内容が分かるようにコメントを記述することも大切です。
以下にPHPのAPIドキュメントを生成するPHP Documentorを使用する際に、記述するコメントの例を紹介します。
大体において、クラスやメソッドなどは先頭にこのようなコメントを記述することが多いと言えます。
・クラス名
/** * * @package パッケージ名 * @author 作成者 * @since PHP7.1 * @version プログラムのバージョン * */
・関数/メソッド名
/** * *関数/メソッド名 * *処理内容 * *作成日 * * @param string $str 第一引数 * @param integer $num 第二引数 * @return array 戻り値の * */
・定数
/** * 説明 * @see 関連する関数1,関連する関数2 */
まとめ
ここではPHPのコメントについて、
- 「//」を使用したコメントの付け方
- 「/* */」を使用したコメントの付け方
- 「#」を使用したコメントの付け方
- HTMLを含む場合のコメント方法
- コメントアウトの注意点
などについて解説しました。
コメントは、ただ処理の内容をコメントするだけではなく、さまざまな用途で使用しますので、普段からコメントの付け方については意識しておきましょう。
もし、コメントの用途や詳細を忘れてしまったら、この記事を思い出してくださいね！
