コメントはどうあるべきか？
コメントは、読んですぐに理解できるような、簡潔で、正確なものであるべき。
それはわかるのですが、すべての処理に書いていたら
ソース全体が読みにくくなってしまいます。
コメントも整理が必要だ。
いらないコメントと必要なコメント
見ればわかるようなことはコメントに書かない方がいい。
// 人間かどうかを判断
if ($object->isHuman() === true) {
// 名前をタロウにする
$name = 'tarou';
}
メソッド名や変数名などの助けもあって、明らかに処理の内容がわかるとき、
わざわざコメントする必要はないと思います。読めばわかるので。
コメントが必要なのは
・なぜこうなるか
・なにをしているのか(これはなにか)
・勘違いしないか
自分が初めて見るコードだと思って見たときに、
この3点で引っかかりそうならコメントを書くようにしています。
なぜこうなるか
// パスワードがない＝本登録していないため対象外
if (empty($user->password)) {
return false;
}
なぜこうなるのか。パスワードがないから対象外なのではなく、
本登録ではないから、ということが重要な事項の場合があります。
そういった場合にコメントを入れています。
これはなにか(なにをしているのか)
// すべての注文額を合計する
$total_amount = array_sum(array_column($orders->toArray(), 'amount'));
PHP関数やフレームワークの持つヘルパ関数などが組み合わさり、
一見してなにをしているのかがわかりづらい場合など、コメントを入れています。
これについては私がプログラム初心者なので、ソースに対する理解度が低く、
入れているということもあります。
ただ、保守などで、今後どういう理解度の方がこのソースを見るかわからないので、
念のためという面もあります。
勘違いしないか
// 管理者へメール(請求管理者とは別なので注意)
$this->sendMailToAdmin($from, $subject, $body);
この場合だと、請求も含んだ処理をしていて、2つの宛先がややこしいなー、
というように感じたので入れています。
間違えてしまいそうだが、決して間違えてはいけないもの
(そんなことばかりですが)、に入れるようにしています。
1年間プログラムをやってきた所感、という内容なので、
ご意見ありましたら頂戴したいです。