PHPコメントの書き方まとめ

PHPのソースコードにコメントを書く時に少し戸惑ったりなぜかエラーや警告になることがあります。コメントの書き方を整理してわかりやすくコードを修正できるようにしましょう。

PHPのコメント

PHPはC/C++などの多くの言語で使われている書き方と同じ書き方をします。ただ、よく戸惑うのはHTML記述と混在しているときのコメント方法ではないでしょうか。その内容も含めてPHPコメントの記述方法を整理したいと思います。

まず、基本的に他言語と同じくPHPも一行コメントと複数行コメントがあります。

一行コメントは、コメントを指定した文字から改行までか、もしくはPHPコードのブロックの終わり「?>」までをコメントにします。改行か「?>」の最初に見つけたほうまでとなります。

一行コメントは「//」もしくは「#」でコメントの始まりを指定します。どちらの文字も同じ機能なので、混在すると混乱の原因となるので使用するときはどちらかに統一したほうがいいでしょう。(一行コメントには「//」だけ使うなど)

例)

<?php
echo 'テスト表示'; // テスト表示命令の一行コメント
?>

赤い部分がコメントとなります。改行か「?>」の最初に見つけたほうまでなので書き方でコメント部分か変わります。

<?php
echo 'テスト表示'; // テスト表示命令の一行コメント
echo '2つ目のテスト表示'; // echo '3つ目のテスト表示'; echo '4つ目のテスト表示'; ?>

赤字部分がコメントとなります。

以下の場合はHTML部分は表示されます。

<h1>画面には<?php // echo 'テスト表示'; ?>が表示されます。</h1>

この場合「画面にはが表示されます。」となります。

複数行コメントは、コメントの始まりと終わりを「/*」と「*/」で指定します。

例)
<?php
/*
echo 'テスト表示'; // テスト表示命令の一行コメント
*/
?>

赤い部分がコメントとなります。この場合echo命令も含めてコメントとなります。

<?php // echo 'テスト表示'; // テスト表示命令の一行コメント ?>

この記述でもecho命令も含めてコメントとなります。ここで注意点として以下のように記述するとコメントが正しくできないのでエラーとなります。

<?php
/*
echo 'テスト表示'; /* テスト表示命令の一行コメント */
*/
?>

最初に現れた「*/」までがコメントとなります。意外と間違いやすいので気をつけましょう。

また、PHPはHTMLと絡んで記述されることがあるので、このときのコメントの書き方に戸惑うこともあると思います。そんなときは複数行コメントを使ってコメントアウトします。

<?php
/*
<h1>画面には
<?php echo 'テスト表示'; ?>
が表示されます。</h1>
*/
?>

複数行コメントを使うとHTML部分も含めてコメントできるので、「<?php /* 〜 */ ?>」を大きな範囲で指定するとまとめてコメントアウトできます。

一般的によく見るPHPのソースコードのコメントは、大きなくくりの説明(ファイルの説明、関数・クラス・メソッドの説明など)は複数行コメントを使い、1つの命令に対するコメントは一行コメントを使っているのをよく見ます。

<?php
/**
 * テスト表示機能: Test class
 */
class Test {
  public function __construct() {
    echo 'テスト表示'; // テスト表示命令の一行コメント
  }
}
new Test;
?>

まとめ

PHPはとくにHTMLと絡んでるときが多いので、コメントを多く書いているときはエラーや警告に陥りやすいです。HTMLのコメント「<!– –>」が絡むとよりややこしくなります。命令ごとの細かなコメントは一行コメントに統一しておくと、大きな範囲で複数行コメントを指定しても間違いが起こりにくいです。コメントの使い方をある程度決めてデバッグ作業が行いやすくなるよう調整しましょう。