2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

【PHP】コメントを書くとき、書かないとき

Posted at

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

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

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

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

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

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

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?