PHPのコメントアウト

PHPは、サーバーサイドのウェブプログラミングで用いられる汎用プログラミング言語です。HTMLに埋め込んで使用されるなど、HTMLのプリプロセッサとして実績があります。PHPはソースコードのメンテナンスのために、多くのコメント機能が実装されています。

ここでは、PHPのコメントアウトの概要から使い方まで解説していきます。

【参考】：PHP

PHPの入門として概要やプログラムの記載方法、文法について解説

コメントアウトとは、プログラミングにおいて、ソースコードのデバッグコードなど不要なコードを無効化したりコードの説明文を注釈として記述したりすることです。PHPではコメントアウトするために、言語仕様にコメント機能を定義して対応しています。

【参考】：PHP

通常、ブラウザで「ページのソースを表示」を選択すると、HTMLではコメントアウト部分も表示されます。PHPは、動的コンテンツを生成するため、PHPでコメントアウトした部分はHTMLのコードには表示されません。

ソフトウェア開発のバージョン情報や変更内容など、情報流出が心配な場合は、PHPのコード部分にコメント機能で注釈を入れることで、コメントの非表示化が可能です。

PHPのコメントアウトの種類と使い方

PHPのコメント機能はいくつかあります。主要なものは、C++型の単一行用のコメント、シェル型の単一行用のコメント、複数行用のコメントの3種類です。まず最初は、これら3種類のコメント機能を学んでいきます。

【参考】：PHP マニュアル / 言語リファレンス / 基本的な構文 / コメント

C++型の単一行用のコメント機能は、”//”を先頭に記述するコメントアウト形式です。”//”は行頭に記述したり、各行の右側に追記したりして使用します。このコメントアウト形式は、行単位で記述します。

使い方は、次のように行います。

<?php
echo 'Hello World';   // ここにコメントを記述します
?>

シェル型の単一行用のコメント機能は、”#”を先頭に記述するコメントアウト形式です。”#”は行頭に記述したり、各行の右側に追記したりして使用します。このコメントアウト形式は、C++型同様に行単位で記述します。

使い方は、次の通りです。

<?php
echo 'Hello World';   # ここにコメントを記述します
?>

複数行をまとめてコメントアウトするには、複数行用に提供されるコメント機能を用います。”/*”でコメントが開始し、”*/”で終了します。単一行でも使用できますが、複数行にわたるプログラムをコメントアウトしたり、説明用の注釈を入れたりする際に利用するのが良いでしょう。

使い方は、次の通りです。

<?php
/*
ここにコメントを記述します
   ：
   ：
*/
?>

複数行用のコメントは、”/*”の後の”*/”で終了します。複数行用コメントの入れ子はできません。次のように記述すると、コメント終了が正しく解釈されずエラーとなります。

<?php
/*
echo 'Hello World';  /* このコメント終了の文字が入れ子になってしまい、エラーとなります */
*/
?>

正常にコメントアウトするには、次のように行ごとのコメントアウトにおいて、単一行用のコメント機能を使います。

<?php
/*
echo 'Hello World'; // このコメントは問題ありません
echo 'Hello World'; # このコメントは問題ありません
*/
?>

これまでに、PHPでは主要な3種類のコメント機能があることがわかりました。それぞれのコメント機能の利用方法には明確な制限がありませんが、プロジェクトなど大規模なソフトウェア開発においては、コメントアウトのルール決めをしておきましょう。

例えば、次の例のようにPHPの大見出しをつけたり、後述するドキュメントコメントを埋め込んだりします。個々の注釈は単一行用のコメント機能を用いるのが良いでしょう。

<?php
//
// 大見出しをつける
//
 
/**
 * ドキュメントコメント（後述します）
 * 提供する機能の概要や、
 * 使用方法などを記載する
 */
 
// デバッグコードを次のようにコメントアウトする
# echo 'Test';
?>

PHPでは、正規表現においてもコメント機能を利用することができます。”(?#”と”)”で囲った部分がコメントアウトされて処理されます。以下の例では、正規表現中にコメント機能で注釈をいれていますが、検索パターンから除外されるため、同じ文字列パターンとして処理が行われます。

<?php
$subject = 'Search Pattern';
$results = preg_match('/Search (?# この部分はコメントアウトされます)Pattern/', $subject);
var_dump($results);
?>

【参考】：PHP マニュアル / 関数リファレンス / テキスト処理 / 正規表現 (Perl 互換) 【参考】：PHP マニュアル / 関数リファレンス / テキスト処理 / PCRE / PCRE のパターン / PCRE 正規表現構文 / コメント 【参考】：PHP マニュアル / 関数リファレンス / テキスト処理 / PCRE / PCRE 関数 / preg_match

また、PCRE_EXTENDEDオプションを設定することで、”#”以降をコメントとしてパターンから除外することもできます。

<?php
$subject = 'Search Pattern';
$results = preg_match('/Search # この部分はコメントアウトされます
Pattern/', $subject);
var_dump($results);
?>

【参考】：PHP マニュアル / 関数リファレンス / テキスト処理 / PCRE / PCRE のパターン / パターン修飾子

ドキュメントコメント（DocComment）とは、”/**”で始まり”*/”で終わるコードのコメントを指します。クラスや関数などの機能や引数、戻り値などを記載するコメントです。次のようにコードの前に、記述しておきます。

<?php
/**
 * Debug Class / デバッグ用クラス （概要を記載）
 * （必要な詳細情報を追加）
 *
 * ＠param int $number　（名前や引数など）
 * @return array | bool　　（戻り値など）
 */
class DebugClass {}
 
$RefC = new ReflectionClass('DebugClass';
var_dump($RefC->getDocComment());
?>

このようにソースコードの保全性を高めるために、コメントを残すなどのルール付けをするのが良いでしょう。上記サンプルコードで使用したgetDocComment()は、ドキュメントコメントを取得する関数です。コードのメンテナンスに使用すると良いでしょう。

【参考】：PHP マニュアル / 関数リファレンス / 変数・データ型関連 / リフレクション / ReflectionClass / ReflectionClass::getDocComment 【参考】：PHP マニュアル / 関数リファレンス / 変数・データ型関連 / リフレクション / ReflectionProperty / ReflectionProperty::getDocComment 【参考】：PHP マニュアル / 関数リファレンス / 変数・データ型関連 / リフレクション / ReflectionClassConstant / ReflectionClassConstant::getDocComment 【参考】：PHP マニュアル / 関数リファレンス / 変数・データ型関連 / リフレクション / ReflectionFunctionAbstract / ReflectionFunctionAbstract::getDocComment

PHP8からアトリビュート（Attribute）機能が追加されています。Javaにおけるアノテーションに相当する機能です。コードの宣言時にメタデータ情報を埋め込むことができます。メタデータの定義と活用を分離することで、ライブラリやフレームワークへの実装が期待されています。

アトリビュートを定義するには、”#[Attribute]”でクラスを宣言します。利用するには”#[クラス名]”です。PHP7まではそのまま”#”で始まるコメントとして解釈されます。

アトリビュート機能は、行頭の”#”を用いて機能追加していますので単一行用のコメント機能の”#”を多様するコードでは、コンフリクトに注意する必要があります。例えば、PHP8以降では”#[コメント]”の様なコードは、シンタックスエラーとなります。

よりコードの安定性を高めるには、コメントの行頭で用いる”#”をあらかじめ”//”に置き換えておくと良いでしょう。

【参考】：PHP マニュアル / 言語リファレンス / アトリビュート

統合開発環境（IDE）やエディタでは、コメントアウトするためのショートカットキーが設定されています。例えばVSCode（Visual Studio Code）では、Windows版では単一行コメントが「Ctrl」+「/」に設定され、複数行コメントが「Shift」＋「Alt」+「A」にマッピングされています。

詳しくは利用中のエディタのドキュメントを確認しましょう。

【参考】：Visual Studio Code: Keyboard shortcuts for Windows 【参考】：Visual Studio Code: Keyboard shortcuts for macOS 【参考】：Visual Studio Code: Keyboard shortcuts for Linux

IDEとは？詳細やメリット、おすすめのIDEを紹介します！

VSCodeとは？定番のコードエディタを他のエディタと比較して解説

HTMLのコメント機能を併用するには

PHPをHTMLファイルに埋め込む場合は、コメント機能を使い分けします。正しくコメントアウトされない場合や、予期せずにコメントアウトされる場合は、使用方法を混同していることが想定されます。

ポイントは、HTMLのコードではHTMLのコメント機能を使用し、PHPのコードではPHPのコメント機能を使用することです。以降で解説するように、PHPでHTMLのコメント機能を使用したりHTMLでPHPのコメント機能をしたりするとコメントアウトされません。

【参考】：PHP マニュアル / 言語リファレンス / 基本的な構文 / コメント

PHP内でHTMLのコメント機能を使用した場合は、PHPがHTMLのコメントを解釈できずコメントアウトされません。次の例は、PHPのコード部分にHTMLのコメント機能を入れた例であり、正しくコメントアウトできません。

<?php
<!--
echo 'Hello World';
-->
?>

HTMLコード部分でPHPのコメント機能を使用した場合も、正しくコメントアウトされません。次の例は、実際のコードでHTMLのコードにPHPのコメント機能を用いた場合です。この場合は、HTMLのタグとして正しく解釈されません。

/*
<?php
echo 'Hello World';
?>
*/

HTMLのコードでPHP全体をコメントアウトするには、PHPの複数行用のコメント機能を使用します。次の例は、実際にPHPのコード全体をコメントアウトした場合の例です。この場合は、PHPのパーサーは正しくコメントとして解釈し、実行コードから除外します。

<?php
/*
echo 'Hello World';
*/
?>

なお、複数行用のコメント機能は入れ子にすることはできませんので、あらかじめコード全体をコメントアウトした場合に、入れ子になっている部分がないか確認して使用します。

HTMLのソースコードに埋め込む場合、コメントタグ内にPHPタグが記述されていても、PHPパーサーは処理を行います。次の例は、PHPタグ全体をHTMLでコメントアウトした例です。

<!--
<?php
echo 'Hello World';
?>
-->

この場合もPHPは動的にコードを生成しますので、HTMLのコメント箇所は次のように生成されます。全体をコメントアウトする場合は、パーサーの処理を理解したうえでコメント機能を利用すると良いでしょう。

<!--
Hello World
-->

PHPのコメント機能はHTMLの理解のもとに活用しよう

PHPは、HTMLのプリプロセッサとして使用できるサーバーサイドの汎用プログラミング言語です。HTMLへの埋め込みを行って使用することが多いため、HTMLの使い方も理解しておく必要があります。

特にコードのコメントアウトを行うには、PHPのみならずHTMLのコードへの影響を与えてしまうので注意が必要です。そのため、ソースコードのメンテナンス時にはHTMLのタグを含めて理解しておくと、より保全性の高いコード開発が可能となるでしょう。

サーバーサイド言語とは？種類や特徴、最近のトレンドも紹介