PHP コメントの書き方

概要

PHP等のプログラミング言語では、どうしてその処理を実行するのか、

ソースだけだと分かりづらい状態になってしまいます。

どうしてその処理を書いたのか分かりやすく日本語などで説明を加えることで、自分以外のプログラマがソースを見た時に瞬時に理解できます。

また、開発途中で一時的にこの処理を動作しないようにするなど、コメントの使い方は様々です。

コメントアウトとは

「プログラムの中に書き込まれた、処理の記述以外の説明文のことをコメントという。」

コメントアウトを使うポイントとしては、メモとして使ったり、
プログラムを一時的に処理しない状態にしたり、
PHP Docというクラスやメソッドの定義前に決まったフォーマットでブロックコメントをすることでドキュメントを自動生成できたりします。

PHPのコメントアウトをしてみる

1行コメント //#

<?php
echo 'プログラミングのテストです。出力されます1。';
//ここは1行コメントになり出力されません。

echo '出力されます2。';

# この行は1行コメントになり出力されません。

echo '出力されます3'; // ここから出力されません。

ブロックコメント /* */

<?php
echo '出力されます1';
/*
 * このブロックは出力されません。
 * ここも出力されません。
 */
echo '出力されます2';

PHP Docサンプル

クラス Class

<?php
/**
 * クラスの1行説明
 *
 * クラスの詳細説明
 * 複数行記述ができます。
 *
 * @access アクセスレベル
 * @author 名前 <メールアドレス>
 * @copyright 会社名 All Rights Reserved
 * @category カテゴリー
 * @package パッケージ
 */

メソッド Function

<?php
/**
 * メソッドの1行説明
 *
 * メソッドの詳細説明
 * 複数行記載することができます。
 *
 * @access アクセスレベル
 * @param int    $id paramは引数を書きます。
 * @param string $name 
 * @return boolean 返り値の型と説明を書きます。
 */
function is_test($id, $name)
{
    return false;
}

まとめ

  • PHPのコメントは3種類
  • 1行コメントとブロックコメントがあります。
  • #コメントは非推奨だけどPythonも同じです。
  • PHP Docを意識して書くことでソースの共有が簡単になります。
  • プログラマしては、コメントが無くてもわかりやすいソースコードにすること大切です。