「一時的に処理を無効にしたい」「他の人にもわかりやすい説明を入れたい」など、PHPでコードを書く中で思ったことはありませんか？そんなときに活躍するのがコメントアウトです。
本記事では、PHPでコメントアウトの基本から応用、HTMLとの違い、トラブルの原因と対処法までを、初心者にもわかりやすく丁寧に解説します。実務で役立つ使い方やVSCodeでの効率的な操作方法、読みやすいコメントの書き方も紹介します。
初心者はもちろん、PHPを学ぶすべての方に向けてわかりやすく解説していますので、ぜひ参考にしてください。
目次
1.PHPでコメントアウトを使う方法
プログラミングするときにおいて、プログラムの説明やメモを記述したり、一時的にコードの一部を無効化したりするためにコメントアウトは重要です。コードの可読性を高め、保守性やチーム開発での生産性向上にも役立ちます。PHPでもコメントアウト機能があります。
ここでは、PHPのコメントアウトに関する基本的な書き方と使い分けについて、PHPを学び始めた初心者でも理解しやすいように解説します。
コメントアウトとは？PHPで使う目的
コメントアウトとは、コード内に記述されていてもプログラムとして実行されないように記述された部分を指します。PHPでは、コメントアウトした部分はサーバー上で無視され出力結果にも影響しません。
PHPでコメントアウトを使う主な用途は次のとおりです。
コードの動作や意図を説明する
テストなどのために、処理を一時的に無効化する
丁寧にコメントアウトされたコードは、第三者に優しいコードとして開発現場で評価されます。個人開発の場合でも、数週間後の自分が理解しやすいようにコメントアウトしておくことをおすすめします。
PHP コメントアウト 書き方を1行・複数行で比較
PHPでは1行だけをコメントアウトする方法と、複数行をまとめてコメントアウトする方法があります。状況に応じて使い分けてください。
種類 | 書き方の例 | 説明 |
|---|---|---|
// | // これは1行コメントです | 最もよく使われる形式で、行の先頭に記述します。 |
# | # これも1行コメントです | シェルスクリプト風の記法です。PHPでは非推奨の場合もあるので注意してください。 |
/* */ | /* 複数行をまとめてコメントアウトできます */ | 長い説明や処理ブロックを無効化したいときに使用しましょう。 |
実際にコメントアウトする形式がプロジェクトごとにルール化されている場合があります。チーム開発する場合は、コーディングガイドなどを事前に確認しておきましょう。
コメントアウトした時のechoや関数処理の結果
コメントアウトによって無効化されたコードは、実行されないだけでなく、出力にも含まれません。たとえば次のコード例のように、echo文をコメントアウトすればブラウザ上に文字列は表示されません。
// echo "この行は表示されません"; |
また、関数定義やif文などの処理全体を一時的に無効にしたい場合も、コメントアウトは有効です。ただし、/* */の範囲を正しく閉じないと、思わぬ範囲までコメント扱いになり、エラーや動作不良の原因になります。
コメントアウトは、いわば見えないけれど存在しているという状態だと理解し、目的を明確にして使ってください。
2.PHPでコメントアウトを複数行するときの注意点
関数や処理ブロック全体を一時的に無効にしたいときなど、PHPで複数行をまとめてコメントアウトしたい場合には複数行コメントアウトしましょう。
複数行コメントアウトする基本ルール
前述の通り、複数行コメントアウトする場合には、コメントアウトしたい部分を「/*」と「*/」で囲んでください。囲んだ範囲はすべてPHPの実行対象外になります。
/* このように複数行にわたって 説明や処理をコメントアウトできます */ |
「/*」と「*/」をセットで使う必要があるので、正確にペアで書く必要があります。片方が抜けていると、後続のコードまで無効化されてしまい、プログラムが正常に動作しなくなる恐れがあるので十分に注意してください。
複数行のコメントアウトが効かない原因
複数行のコメントアウトをしたはずなのに無効化されていない場合、次の点を確認してみてください。
「/*」または「*/」の記号が抜けていませんか？
閉じタグ「*/」の位置がズレていませんか？
コメントの中に意図しない記号や構文が含まれていませんか？
「/」や「*」が全角になっていませんか？
たとえば、以下のようなコードではコメントアウトが正しく反映されません。
間違っているコード例
/* echo "この行は表示されません"; // しかし、ここで閉じ忘れると... echo "この行も無効になります"; |
閉じ記号「*/」を書き忘れると、続く処理まですべてコメント扱いとなってしまいます。PHPはコメントの終了が見つからない場合、ファイルの末尾までコメントと判断しますので、画面に何も表示されず動かない！となってしまうこともあります。
コメントアウトはネストしても大丈夫？
PHPの複数行コメントはネスト構造・入れ子構造に対応していません。/*～*/でコメントアウトした中にさらに/*～*/を記述すると、意図通りに動作しません。
間違っているコード例
/* この中に別のコメントを書くと /* ネストしたコメント */ エラーや予期せぬ挙動の原因になります */ |
このコード例では、最初の*/でコメントが終了したと解釈され、それ以降の構文にエラーが発生します。複数のブロックを段階的にコメントアウトしたい場合は、//を使って1行ずつ処理を無効化する方法がおすすめです。
おすすめするコード例
//複数のブロックを段階的にコメントアウトしたい場合は //1行ずつ処理を無効化する方法がおすすめです。 //エラーや予期せぬ挙動を防ぐことが可能です |
3.PHPでコメントアウトされないときの原因と対処法
PHPでコメントアウトしたはずなのに、思った通りにコードが無効化されていない経験はないでしょうか？文法ミスや記号の位置関係、HTMLとの混在が原因になっている可能性があります。ここでは、PHPで想定通りにコメントアウトされない原因と、それぞれの対処法について解説します。
PHPでコメントアウトされない原因
想定通りコメントアウトされない場合、次のような原因が考えられます。
「/*」や「*/」の書き忘れ、位置のずれ
「/」や「*」が全角になっている
コメント記号の中に構文上問題のある文字列が含まれている
PHPタグ外でコメントアウトしようとしている
PHPとしてコメントアウトしたつもりが、実際にはHTMLとして認識されている
1～3.の原因については前述しました。4.と5.の原因については、PHPを使ったプログラミング経験を持つ人でもはまってしまう恐れがあります。PHPとHTMLを混在させたコードの中でコメントアウトするときには注意しましょう。
PHPのコメントアウトはタグ内のみで機能します
PHPは <?php ... ?> のように、PHPタグの内側にコードを書くことで初めて処理されます。
コメントアウトも例外ではなく、タグの外にある場合はPHPのコメントとしては無効です。当たり前のように感じられるかもしれませんが、PHPとHTMLを混在して扱っていると混乱してしまうことがあるので、ぜひ頭の片隅に置いておいてください。
// これはPHPのコメントアウトではありません。そのまま出力されます。
?> |
同じコメントアウトでも、PHPとHTMLでは形式や記述位置が異なるため、混同しないようにしてくださいね。テンプレートやCMSを扱っている場合には特に意識が必要で、PHPタグの外にコメントアウトを書かないようにしましょう。
コメントアウトする位置や改行の問題によるエラー例
コメントアウトを書く時の位置ズレや改行ミスが、意図しないエラーの原因になることもあります。また、コメントの途中で構文的に意味を持つクォーテーションや制御構文などを入れてしまうと、パースエラーになることもあります。
意図通りコメントアウトさせるには、コメントアウトしたい処理ブロックの開始・終了が明確な範囲で使いましょう。また、複数行をコメントアウトする場合は、改行位置やインデントを整えることをおすすめします。いずれもコメントアウトの基本として身につけてくださいね。
4.PHPとHTMLのコメントアウトの違いを正しく理解しましょう
PHPでWebページを作成していると、HTMLとPHPのコードが混在することが多いです。思わぬトラブルを避けるために、ここではHTMLとPHPのコメントアウトの違いを正しく理解できるように解説します。
PHPとHTMLでコメントアウトの違いを比較
HTMLとPHPでは、コメントの記述方法と処理のされ方がまったく異なります。
言語 | コメントの書き方 | 特徴 |
|---|---|---|
HTML | <!-- コメント内容 --> | ブラウザに表示されないが、ソース上には残ります。 |
PHP | // コメント | サーバー側で処理が無視され、HTMLには出力されません。機密性の高い情報やデバッグ用のメモは、PHPのコメント形式で記述するのがより安全です。 |
/* コメント */ または /* 複数行コメント */ |
HTMLとPHPを同時に扱う場合のコメントアウトに関する注意点
HTMLとPHPが混在するコードでは、どちらのプログラミング言語のコメント形式を使わなければいけないのか意識することがポイントです。記述位置やタグの切り替わりを正確に把握していないと、意図しない動作や表示トラブルの原因になってしまうでしょう。
PHPの初心者が混乱しやすいコード例をいくつか紹介しましょう。
<?php echo "<!-- 表示されないけど、HTMLとして出力されるコメントアウト -->"; ?> |
このコード例は、コメントアウトされているように見えるかもしれませんが、HTMLコメントとして出力されます。画面には何も表示されないものの、ソースを見ればコメントが残っている状態です。セキュリティ上の考慮が必要な場合には、このような記述は避けなければなりません。
<!-- <?php echo "この部分は処理されません。"; ?> --> |
このコード例では、PHPで書かれたコードがHTMLのコメントアウトで囲われているため処理されません。PHPとしてコメントアウトしたいなら、次のコード例が正解です。
<?php // echo "この部分は処理されません。"; ?> |
HTMLとPHPを同時に扱う場合には、どこからどこまでがPHPなのかを意識することが重要です。
5.PHPでコメントアウトしたいときVSCodeでの方法
Visual Studio Code（VSCode）は、PHP開発でも利用されている人気のエディタです。VSCodeにはコメントアウトを効率化するショートカットや拡張機能が用意されています。
ここでは、PHPのコメントアウトをVSCodeで取り扱う方法などを紹介します。
VSCodeで使えるPHPコメントアウトのショートカット
VSCodeでPHPのコードをコメントアウトする場合、ショートカットを使うと便利です。
操作 | Windows / Linux | Mac |
|---|---|---|
1行コメント | Ctrl + / | Cmd + / |
複数行コメント | 範囲選択後に Ctrl + / | 範囲選択後に Cmd + / |
ショートカットを使えば、カーソル位置の行や選択範囲に自動で//が挿入され、複数行をコメント化したい場合でも、範囲選択から一発でコメントアウトできます。解除したい場合には、同じショートカットをもう一度使ってください。
VSCodeで複数行を一括でコメントアウトする方法
VSCodeでショートカットを使って複数行を一括でコメントアウトすると、「//」が各行の先頭に追加されるため、実質的には1行コメントの連続になります。
「//」による1行コメントの連続は、コメントアウト後でも個別の行を有効化しやすく、デバッグ中や一時的な無効化に向いています。一方で、完全にブロックとして無効化したいときは、「/*～*/」を使った複数行コメントがおすすめですが、VSCodeでは手動で使わなければいけません。コードの規模や用途、コメントアウトの目的、コーディングルールなどを踏まえて使い分けてください。
PHPとHTMLが混在する場合に便利
PHPとHTMLが混在したコードでは、コメントアウトのショートカットを使うと便利です。
たとえば、PHPタグの外でショートカットを押すと、VSCodeは自動的にHTMLコメントである「<!-- -->」を挿入します。一方でPHPタグ内で同じ操作を行えば、「//」によるPHPコメントを挿入します。
拡張機能でコメントを効率的に管理するには？
コメントの操作性を高める拡張機能をVSCodeは持っています。たとえば、次のような拡張機能を導入することで、より視覚的にコメントを整理したり、チーム開発で役立つメモを残したりできますので、ぜひ採用を検討してみてください。
TODO Highlight：「// TODO:」のようなコメントを色付きでハイライトする
Better Comments：コメントの種類ごとに色分けできる（重要／質問／警告など）
PHP Intelephense：コメント含めコード全体を解析して補完・整形を支援する
関連記事
PHP開発環境構築｜Docker・VSCode・XAMPPなどWindows・Mac対応の完全ガイド
6.PHPでコメントアウトを活用しましょう！使いこなすヒント
開発現場ではコメントアウトは単なるメモ書きではなく、コードの整理やデバッグ、チームでの意思疎通にも役立ち、実務で欠かせない技術のひとつといえるでしょう。もちろんPHPを使ったコーディングでも同様です。
ここではコメントアウトの具体的な活用シーンを紹介し、コメントアウトがどのように役立つかについて解説します。
テストやデバッグでコードを一時停止させる
プログラムの一部だけを無効化して挙動を確認したいとき、コメントアウトは非常に便利です。たとえば、エラーが起きた場合に、どの処理が原因かを探るため、段階的にコードをコメントアウトして確認することがあります。
たとえば次のように順にコメントアウトし、トラブルシューティングします。
// ユーザー情報を取得（現在は無効化） |
影響を与えずにコードの一部を停止できるため、デバッグ作業が効率的になります。一時的に無効化した部分を簡単に元に戻せる点も、コメントアウトの便利な点です。
チームでの開発時に他のエンジニアとのコミュニケーションに活かす
複数人での開発では、他の開発者がコードの意図をすぐに理解できるようにすることが求められます。そのためコメントを活用して処理の目的や注意点を明記することが一般的です。
// フォーム送信時のバリデーション処理（未完成） // 条件分岐は今後追加予定 |
このようなコメントは、次に作業を引き継ぐエンジニアにとって大きな助けになります。
また、コードレビューの際にも意図が伝わりやすくなるため、チーム開発においてコミュニケーションの質を高める効果が期待できるでしょう。
開発中の処理を非表示にして保留する
仕様変更や追加機能の実装中など、処理を一時的に保留しておきたい場合にもコメントアウトは有効です。たとえば、将来的に使う予定の関数や処理を、いったん無効化しておき、再び必要になったときに復元する、という使い方が可能です。
/* sendNotification($email, $message); // 通知機能は次回リリースで有効化予定 */ |
このコード例のように実行はさせずに、記録としてコードを残すという使い方もコメントアウトの強みです。削除してしまうと再利用が難しくなりますが、コメントとして残しておけば、必要に応じ簡単に復元できます。
関連記事
PHPプログラミングとは？将来性や実践で活用できるコード例など初心者にわかりやすく解説
PHPのdate関数完全ガイド｜フォーマット表示からstrtotime・日付比較・WordPress実装まで
7.読みやすいコメントアウトのコツ
コメントアウトは単にコードを無効化するだけでなく、コードの意図や処理内容を伝えるための重要な手段です。しかし、伝わりにくいコメントや、逆に冗長すぎる記述は、かえってコードの可読性を下げてしまいます。上手なコメントアウトには、ある程度の経験やスキルが求められるでしょう
ここでは、初心者が押さえておきたい読みやすいコメントアウトのコツを紹介します。
コメントアウトの目的と適切なボリューム
まず大前提として、なぜその処理があるのか？どうしてそのようなコードになっているのか？などを説明するために使うのが、コメントアウトする基本的な目的です。単に何をしているかを繰り返すだけでは、まったく意味がなく、むしろコードを読む妨げになってしまいます。
悪いコメント例（コードの内容をそのまま書いただけ）
// $xに1を代入 $x = 1; |
良いコメント例（理由を説明している）
// 初期状態ではカウントを1から開始する $x = 1; |
また、コメントが長くなりすぎると逆効果です。要点を簡潔にまとめ、1〜2行程度に収めるのが理想的です。もし長文のコメントが必要な場合は、関数や処理などコードを見直すべきかもしれません。
良いコメントと悪いコメントの違い
読みやすいコメントを書くための基本的なポイントをまとめてみましたのでぜひ参考にしてみてください。
ポイント | 良いコメント | 悪いコメント |
|---|---|---|
内容の明確さ | なぜその処理を行っているか説明 | 処理内容をそのまま繰り返しているだけ |
長さ | 簡潔で適度な分量 | 不要に長く、読みにくい |
更新性 | 実際の処理と整合している | 処理と内容が食い違っている |
なお、悪いコメントの典型例は、コードを変更したのにコメントを更新し忘れてしまうパターンです。誤った説明があると、かえって混乱を招くためコメントは常に最新の状態を保ちましょう。
チームで共有しやすいコメントの書き方
チーム開発においては、メンバーごとに書き方がバラバラだと、読み手にとって理解しづらくなってしまい開発効率が落ちてしまいます。コーディングルールの中に、コメントアウトのルールについても統一することをおすすめします。
たとえば、次のようなルールを検討してみてください。
コメントの先頭に「TODO」や「NOTE」などのラベルを付ける。
コメント内の文体を文末「〜する」や「〜です」に統一する。
単語や略語の意味を簡潔に明記する（例：ID、UID、PIDなど）
コード例
// TODO: バリデーション処理を追加する予定
|
こうしたルールを作りチームで共有することで、誰が見ても理解しやすいコードを保つことができます。わかりやすいコメントアウトがあることで、開発効率が高まったり、トラブル発生時の対応がしやすくなったりすることがあるはずです。
8.PHPDocとは？コメントアウトとの違いと役割
PHPDocとはコメントの一種で、「/** ～*/」で記述し、機械的に解析できる形式のコメントです。PHPDoc内部には@paramや@returnなどのタグを使って関数やメソッドの情報を明示します。
通常のコメントとの違いは、人間だけでなくツールにも読ませることを前提としている点です。PHPDocを記述しておくと、VSCodeやPhpStormなどのIDEを使った自動補完やリファレンス表示が強化され、開発効率が上がることが期待できます。
PHPDocを使った関数説明の例
実際に、PHPDocを使って関数にコメントをつけた例を紹介します。
/** * ユーザーの年齢を計算する関数 * * @param int $birthYear 生まれた年（西暦） * @return int 現在の年齢 */ function getAge($birthYear) { return date('Y') - $birthYear; } |
このように記述することで、関数の目的や引数の型、戻り値の型がひと目でわかるようになるはずです。また、IDE上で関数にカーソルを当てたときに、説明文や引数情報がポップアップ表示されるようになるのも大きな利点です。
初心者でも使えるPHPDocの使い方
PHPDocの記述自体はコメントの一種であるため、PHPコード内に書くだけで利用可能です。特別なライブラリや外部ツールの導入は不要で、今すぐ始めることができます。
PHP初心者などPHPDocに慣れないうちは、次のような最低限の情報を記述するところから始めてはいかがでしょうか。もちろん、チームで使うコーディングガイド・コメントアウトルールは守りましょう。
関数やクラスの目的を1〜2行で簡潔に書く
@param タグで引数の型と名称を明示する
@return タグで戻り値の型を記載する
PHPDocに慣れれば、@throws や @deprecated などのタグを活用して、より正確な仕様の明示や管理をめざしてください。
PHPDocは、チーム開発や、特に長期のプロジェクトにおいて、コードの信頼性と可読性を向上させる強力な武器になります。ぜひコメントアウトに加えて、PHPDocも活用してみてください。
関連記事
Laravel【PHP】とは？入門のためのインストール方法やコード付きで使い方をわかりやすく解説
9.PHPのコメントアウトについてよくある質問（FAQ）
PHPのコメントアウトはシンプルな機能にも見えますが、注意しなければいけない点もあります。ここではPHPのコメントアウトに関して初心者が抱きやすい質問などを踏まえ、よくある質問について紹介します。
コメント内にコメントは書けるの？
PHPでは、コメントの中に別のコメント記号を入れることは避けるのが安全です。特に「/*～*/」で囲んだ複数行コメントの中に、さらに「/*」を入れると、意図しない場所でコメントが終了してしまいます。
/* これはOK // この中に1行コメントを入れても動作に影響はない /* ← これはNG：ネストした時点で構文エラーの原因になる */ |
どうしても多重の説明が必要な場合は、「//」を使って1行ずつコメントアウトするのが安全でおすすめです。
コメントアウトすることでコードが壊れることはある？
基本的に正しくコメントアウトするとプログラムの動作に影響しません。閉じタグ（*/）の書き忘れや、不適切な位置へのコメント挿入によって、コード全体が無効になったり、実行エラーが発生する恐れは十分に考えられるでしょう。
コメントに全角文字や日本語を使っても良い？
はい、問題ありません。PHPのコメントには全角文字や日本語を使用できます。ただし、ファイルの文字コード設定が適切でないと、文字化けやエディタ上の表示不具合が発生することがあります。開発環境を構築する際に十分に確認と対応をしておきましょう。
エディタやIDEで同じ文字コードを使用するよう統一するなど、環境が整っていれば、日本語でコメントを書くことは問題ありません。
コメントアウトするとコードが重くなる？
コメント自体はPHPの処理対象外となるため、サーバー上での実行速度には影響しません。そのため一般的には、コメントアウトすることでコードが重くなることは考えられません。
一方で、極端に長いコメントや大量の不要な説明文を残していると、コードの可読性が落ちてしまい、保守性が低下してしまいます。コメントアウトはあくまでコードの補助的な役割として捉え、必要最低限の情報を簡潔に書くことをおすすめします。読み手の視点を意識して、目的の伝わるコメントを心がけましょう。
コメント内に機密情報を残しても大丈夫？
結論から言うと、コメントにパスワードや認証キーなどの機密情報を残すのは非常に危険です。たとえPHPのコメントがサーバー側で処理されず、出力結果に含まれないとしても、誤ってHTML内に残したり、Gitで公開してしまったりするリスクがあるためです。
たとえば次のようなコメントは、絶対にやってはいけません。
// DB接続用のパスワード：password123（本番用） |
このような機密性の高い記述がソース管理やレビュー時に漏れてしまうと、深刻な情報漏洩につながってしまう恐れがあります。また、CMSやテンプレートエンジンの中では、コメントが意図せず出力に含まれてしまう場合もあるため、絶対に油断は禁物です。
コメントアウトを安全に使うポイントは次の通りです。
コメントには、処理の説明や意図など非機密の内容だけを書きましょう
本番環境のパスワードやAPIキーは絶対にコメントに残さない！
セキュリティに関わる情報は、別ファイルや環境変数で管理しましょう。
コメントはコードの理解を助ける強力な手段ですが、書き方を間違えるとセキュリティホールになる危険性もあることを忘れないようにしてください。
また、機密情報ではなくても、品性を疑われるような記述も、コメントとはいえ避けましょう。
10.まとめ
この記事では、PHPにおけるコメントアウトの基本的な書き方から、複数行の注意点、HTMLとの違い、VSCodeでの操作方法、さらには実務での活用法やPHPDocとの違いまでを幅広く解説しました。
PHPに限らず、プログラミングにコメントアウトは欠かせないスキルです。コメントアウトを上手に使えば、開発効率だけでなく、チームとの連携も大きく向上します。ぜひこの記事を参考に、実際のコードにコメントを取り入れ、理解しやすく伝わるプログラミングを実践してください。
プログラミングやPHPを学び始めた初心者、開発現場でコードの可読性を高めたい方にとって、本記事が皆様にとって少しでもお役に立てますと幸いです。
「フリーランスボード」は、数多くのフリーランスエージェントが掲載するITフリーランスエンジニア・ITフリーランス向けの案件・求人を一括検索できるサイトです。
開発環境、職種、単価、稼働形態、稼働日数など様々な条件から、あなたに最適なフリーランス案件・求人を簡単に見つけることができます。
単価アップを目指す方や、自分の得意なスキルを活かせる案件に参画したい方は、ぜひ「フリーランスボード」をご利用ください。
自身に最適なフリーランスエージェントを探したい方はこちらよりご確認いただけます。