PHPでコメントを書く方法やオススメの書き方！

PHPでプログラムにコメントを書く方法や、オススメの書き方について記載しています。

コメントはプログラムに説明を付けることです。
プログラムの中でコメントにした箇所は、プログラムとして認識されないようになります。

1行コメントを書く

1行のコメントを書く場合には、下記のようにスラッシュをふたつ使います。
「//」以降がコメントになるので、プログラムから無視されます。

<?php
// 果物名を格納する変数です。
$fruit = '';
$fruit = 'apple'; // リンゴを英語で格納

echo $fruit;

上記のように、コメントを入れることが可能です。
コメントはプログラムの中では無視されて、このプログラムは文字列の”apple”が出力されるだけです。

複数行のコメントを書く時には「/*」から始めて「*/」で終わるようにコメントを書きます。
具体的には下記のようにします。

<?php

/**
 * 「Hello, World」を出力する関数
 * @return void
 */
function hello() {
    echo "Hello, World";
}

echo hello();

関数にコメントをつけてみました。
関数にコメントを付ける場合には、このようにPHP Documenter形式で書くと良いです。
複数行のコメントもプログラムとしては、もちろん無視され、このPHPファイルの出力結果は「Hello, World」になります。

「#」も1行コメントとして機能します。
1行コメントの「//」のプログラムを「#」で書き換えると、このような形になります。

<?php
# 果物名を格納する変数です。
$fruit = '';
$fruit = 'apple'; # リンゴを英語で格納

echo $fruit;

もちろん、コメントは無視されて、出力結果は「apple」になります。

コメントアウトはプログラムをコメント化して、処理が行われないようにしておくことです。
今後使いそうな処理の場合はコメントアウトしておくと良いかもしれません。

昔は下記のようにコメントアウトを駆使して、追加や削除したコードを残しておく。みたいなことをやっていた時期もありました。

<?php

// 2010.01.01 DELETE START
// $hoge = "何らかの古い処理";
// 2010.01.01 DELETE END
// 2010.01.03 ADD START
$hoge = "何らかの新しい処理";
// 2010.01.03 ADD END

現在ではGitなどのバージョン管理ツールで、ソースを管理することが普通かと思います。

消した差分などはツールの方で管理されて、参照したり復活させたりすることが簡単にできます。
もう使わなそうなソースはコメントアウトでなく消すことをオススメします。

複数行コメントで書きましたが、関数やクラスなどにはPHP Documentorの仕様に沿って、コメントを書くのがおすすめです。
PHP Documentorの仕様に沿って書いておけば、PHP Documentorを使って、HTML形式のドキュメントが出力されます。

今回はコメントを書く方法について記載しました。
基本的にはPHP Documentor(PHP Doc)の仕様に沿って書いておくと良いかと思います。

処理の中にコメントを書く場合は、処理を見て簡単にわかりそうな場合には必要ないかと思います。
むしろ、コメントがなくてもわかるような処理を書くことが望ましいです。

全体を通して、わかりにくい箇所などには、コメントをつけておくと良いかと思います。
コメントを増やしすぎると、コードが見にくくなりますし、少なすぎると後日「なにやってた…?」となってしまいます。
過不足ないように気をつけたいところですね。