コメントの書き方

これまでの学習内容をプログラム上にも残したいので、「FirstStep.php」の8行目に新たな行を追加して、カタカナで「エントリーポイント」と入力してみましょう。

すると、PHPのプログラムとしては全角文字（ひらがな・カタカナ・漢字など）が使えないため、赤い下線が出てエラーとなるはずです。

そこで、新たな8行目にカーソルがある状態で、下表のショートカットキーを入力してください。

行コメントの切り替えショートカット

「エントリーポイント」の前に「// 」（スラッシュ2つと半角スペース1つ）が挿入され、文字が緑色に変わり、エラーが消えました。この状態をコメントと言います。

もう一度ショートカットを入力すると、コメントが解除されます。

先頭の「// 」は手入力でも構いません。積極的にプログラム内に理解した内容のメモを残すようにしましょう！また、プログラム自体もコメントにすることができ、それをコメントアウトするといいます。いろいろ試す際に元のプログラムを残したい、という場合に活用しましょう！

なお、基本的にサンプルコードではコメントを省略しますので、コピー＆ペーストなどの際にせっかく書いたコメントを消してしまわないように注意しましょう。

長いプログラムをコメントアウトするような場合、ブロックコメント（複数行コメント）という方法も使用できます。

行番号の「6」から「14」をドラッグ（「6」の真上でマウスボタンを押して、離さないまま「14」までポインタを移動させ、「14」の真上でマウスボタンを離す）すると、6行目から14行目をすべて選択することが可能です。

その状態で下表のショートカットキーを入力してください。

ブロックコメントの切り替えショートカット

すると、6行目には「/* 」（スラッシュとアスタリスクと半角スペース）が、14行目にはその反対向きが挿入され、クラスのブロック全体が緑色のコメントアウト状態となりました。この開始終了マークも手入力が可能です。

もう一度同じ操作を行い、ブロックコメントを解除しておきましょう！

本来、コメントは自分用のメモだけではなく、他の開発者への説明書という目的が大きいです。特にクラスやメソッドには、それを使う人がプログラムの中身をすべて読まなくても、何が行われるのかを把握できるような説明を付けることが理想的です。

そのようなコメントの書き方は様式化されており、それをPHPDocコメントと言います。

では、9行目に新たな行を追加して、そこで「/**」（スラッシュ1つとアスタリスク2つ）を入力して「Enter」で改行してください。

PHPDoc形式のコメントのフォーマットが出現しました。次のサンプルコードのようにコメントを完成させましょう。

<?php
// プログラムの実行箇所
FirstStep::main();

// プログラムの定義
class FirstStep
{
    // エントリーポイント
    /**
     * これはエントリーポイントです。
     * 実行すると「Hello!」と出力します。
     */
    public static function main()
    {
        // 処理
        echo 'Hello!';
    }
}

PHPDocの様式に従うと、VSCodeのようなツールではそれを解析し、下図のようにメソッド名などにマウスオーバーすると詳細が表示されるようになります。

メソッド名「main」にマウスオーバーした状態

学習中や趣味の開発ではそこまで厳密にPHPDocコメントを書く必要はありませんが、仕事での開発では必須となります。また、自分の書いたプログラムでも、1か月も経てば他人の書いたプログラムと同じです。書いたときに考えていたことを忘れてしまって、もう一度解析するなんてことにならないよう、日ごろから書く習慣をつけておくと良いでしょう。