##コメントはどうあるべきか？

コメントは、読んですぐに理解できるような、簡潔で、正確なものであるべき。
それはわかるのですが、すべての処理に書いていたら
ソース全体が読みにくくなってしまいます。

コメントも整理が必要だ。

##いらないコメントと必要なコメント

見ればわかるようなことはコメントに書かない方がいい。

// 人間かどうかを判断
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年間プログラムをやってきた所感、という内容なので、
ご意見ありましたら頂戴したいです。