コメント

これから学ぶPHP 第2回

プログラムは書いたら終わりではありません。レビューをしてもらったり、機能を追加したり、不具合を直したり、何度も読み直す機会があるでしょう。しかし、何千行もに膨れ上がったコードを読み直したり、直したい場所を探すのはとても大変です。そこで、今後プログラムのコードを読む人のためにも、どのような処理がそこに書いてあるのかについて、コメントを書いておくことが重要です。「今後プログラムのコードを読む人」というのは未来の自分も含みますよ！昔の自分が書いたコードでも、後から読むとちんぷんかんぷんになってしまうことは珍しくありません。

コメントの書き方は3通りあります。

（1）#を使う方法

# 記号から行の最後までがコメントになります。少し古い書き方です。

    <?php
    # echo "この文は出力されません";
    echo "この文は出力されます";
    echo "行の途中からもコメントを書けます"; # これはコメントです
    ?>

（2） //を使う方法

// 記号から行の最後までがコメントになります。一般的な書き方です。

    <?php
    // echo "この文は出力されません";
    echo "この文は出力されます";
    echo "行の途中からもコメントを書けます"; // これはコメントです
    ?>

（3）/* と */を使う方法

開始記号 /* から終了記号 */ までがコメントになります。複数行に渡るコメントを書くときに使えます。

    <?php
    /*
    echo "この文は出力されません";
    echo "この文も出力されません";
    */
    echo "この文は出力されます";
    echo "行の途中からもコメントを書けます"; /* これはコメントです */
    ?>

ところで、コメントには何を書けばいいのでしょうか。例を見てみましょう。

悪い例（1）

    <?php
    // 日付を表示する
    echo date("Y/m/d");
    ?>

このコメントには、コードに書いてある以上の情報がありません。このような無駄なコメントならば、書かない方がいいでしょう。

良い例（1）

    <?php
    // 今日の日付を表示する
    echo date("Y/m/d"); // 例：2014/07/01
    ?>

このコメントは意味のあるコメントです。なぜなら、第三者でもコードが合っているかどうかを判断しやすいからです。

悪い例（2）

    <?php
    // フラグが1なら
    if ($flag === 1) {
      // ○○する
    }
    // フラグが1でないなら
    else {
      // ××する
    }
    ?>

このコメントも悪い例です。「そんなのは見れば分かるよ！」というコメントしか書いてありません。

良い例（2）

    <?php
    // 見ている人が管理者なら
    if ($flag === 1) {
      // ○○する
    }
    // 見ている人が管理者でないなら
    else {
      // ××する
    }
    ?>

このコメントならば、「このフラグには閲覧者が管理者かどうかの情報が入っている」ことと「ここでは管理者かどうかで処理が分岐する」という情報が得られます。

また、処理の大きな区切りの場所にも、区切りが分かりやすいコメントを書くといいでしょう。コードを書いた日付や、書いた人の名前を書いてもいいかもしれません。書き方は個人の好みや、開発チームのルールがあると思います。

    <?php
    /*
      diary.php
      日記関連の処理
      
      作成日 2014/06/23
      作成者 noda
      更新日 2014/06/28
      更新者 noda
    */
    
    //--------------------------------------------------
    // 最新の日記をデータベースから取得する
    //--------------------------------------------------
    
    （長い処理ほにゃらら）
    
    //--------------------------------------------------
    // 最新の日記への返信をデータベースから取得する
    //--------------------------------------------------
    
    （長い処理ほにゃらら）
    
    ?>

余談ですが、プログラム中に書いたコメントを抜き出して、ドキュメントを作れるソフトウェアがいくつかあります。自分でドキュメントを書くのは大変なので、自動化してしまおうというソフトですね。それらのソフトウェアには、それぞれのコメントの書き方のルールがありますよ。

今回は以上です。

それではまた～。よい開発ライフを！