PHPのソースコードにコメントを書く方法【初心者向け】

【初心者向け】PHPを使ったコメントアウトのコードを紹介

PHPのコメントとは

コメントとは、特定の記号を使って、その内側に記述したソースコードを処理されないようにすることです。実行したくない行をコメントにすることをコメントアウトと言います。

コメントを残す意味

これは大きく分けて２つあります。

• 人に対して、ソースコードの意図を伝える。
• コードを部分的に決してテスト動作させたいときに、コメントアウトする。

誰のためにコメントを残すのか

一つは、自分のためです。たとえ一人で触るソースコードであっても、時間が経過してから見直した時に理解に時間がかかってしまうのは合理的ではありません。そこで、未来の自分のために実装の意図についてコメントを残します。PHPの勉強を始めたばかりの人は、実装の意図を残すよりも、ソースコードを日本語にする方が効果的でしょう。

<?php
// 省略
// ifは条件によって処理を分岐させる
if ($a > $b) {
  // $aが$bよりも大きい場合
  echo "aはbより大きい";
} else {
  // $bが$aよりも大きい場合
  echo "bはaより大きい";
}
?>

もう一つは、このソースコードを触る他の人のためです。ソースコードだけで実装の意図が他の人に伝わることが一番良いですが、現実的に難しい場合があります。そういう時は、他人にソースコードの意図を伝えるためにコメントを残すようにしましょう。

コメントアウトが使用される例

どのような処理をこれからするか示す

長いコードになってくると、どこからなんの処理をしているかが、わかりづらくなってしまいます。それを防ぐために、下のようなコメントを残して、このブロックはこの処理をしていますということを明示的にしています。

//****************************************
//     ログイン処理
//****************************************
if ($passwd == $_POST['passwd']) {
// 省略
}

定数、変数の挙動を書く

定数、変数は、ソースコードを書いた瞬間は意味を覚えていても、時間が経つと何を表しているのかわからなくなることがあります。それを防ぐためにコメントを残します。

/**
* twitterの文字数制限の定数
*/
const TWITTER_STRING_LIMIT = 140;

// 0: 未契約 1: 仮契約 2: 本契約
$agreement_flg = 0;

関数の挙動を書く

phpDocumentorというコメントから自動でドキュメントを生成するツールがありますが、関数の引数、戻り値はそれに沿って書くことが多いです。下のソースコードがphpDocumentorのフォーマットに沿ったソースコードです。

/**
 * ユーザIDがデータベースに存在するか確認する
 *
 * @param int $user_id
 * @return bool
 */
function hasUserId($user_id)
{
// 省略
}

コメントの書き方

PHPでのコメントの書き方は、2種類の一行コメントと1種類のブロックコメント合わせて、3種類のコメントの記述方法があります。

一行コメント

一行コメントは、改行またはPHPコードのブロックの終わりのどちらかまでコメントになります。コメントの開始を示す記号は、//スラッシュ２つか#ハッシュ記号のどちらかです。

<?php
echo "<p>PHPのコメントのテスト</p>"; // この部分がコメントです。
 # ここもコメントになります。 ?> <p>ここは表示されます</p>

複数行コメント

複数行まとめてコメントする時はブロックコメントを使用します。ブロックコメントは/*で始まり*/で終わります。

<?php
/*
  echo "ここはコメントです。";
  echo "ここもコメントです。";
*/
echo "コメントのテスト";
?>

複数行のコメントでやりがちなミス

ブロックコメントは、最初に*/が現れた時点で終了します。入れ子にしようとすると失敗するので注意が必要です。

<?php
/*
  echo 'テストです'; /* このコメントのように入れ子にすることはできないです。 */
*/
?>

エディターのショートカットでコメントアウトする

実は、ほとんどのエディターには、カーソル行をコメントアウトするショートカットがあります。SublimeTextとAtomを見てみましょう。

SublimeText

Windows: Ctrl + / または Ctrl + Shift + /

Mac: Command + / または Command + Shift + /

Atom

Windows: Ctrl + /

Mac: Command + /

ショートカットを活用すれば、試しに実行したくないソースコードをすぐにコメントアウトできます。

まとめ

コメントの使い方は決して難しくありませんが、大事なのはコメントを記載する時のコンテキストを意識することです。特に複数人で開発するときは、誰のためになぜコメントするのかを意識してコメントしてみてください。ソースコードは、大規模になものになると必ず複数人で開発することになるので、コメントを通して適切なコミュニケーションを図るようにしましょう。

参考文献

「パーフェクトPHP」小川雄大、柄沢聡太郎、橋口誠、著、技術評論社、2010

「PHP マニュアル 言語リファレンス 基本的な構文」http://php.net/manual/ja/language.basic-syntax.comments.php

「Webデザインのタネ Sublime Textの地味に便利なショートカット５つ」http://blog.1dz.jp/?eid=805

「【Atom】ショートカット（Win・Mac）とおすすめパッケージ」https://qiita.com/4cres/items/cb3356ea0de2835957f0