コードのコメントは書くべきか？
コメントは書くべきか書かないべきか、開発者の間で意見が割れる。多すぎると邪魔になり、少なすぎると後で読めなくなる。問題はコメントの有無ではなく、何を書くかだ。
コメントが害になるとき
- コードを読めばわかることを、そのまま日本語で繰り返している
- コードが変わったのに、コメントだけ古いまま残り、嘘になっている
- コメントで補うことで、わかりにくいコードがそのまま放置される
コメントが効くとき
- なぜそうしたか、という意図や背景を残すとき
- 一見不自然な処理の理由（回避策や制約）を説明するとき
- 呼び出し側が知るべき前提や副作用を伝えるとき
実用的な結論
書くべきは「what」ではなく「why」だ。
- 何をしているかはコードで語らせる。名前と構造で読めるようにする。
- なぜそうしたかはコメントで残す。コードからは読み取れないから。
- コメントを書きたくなったら、まずコードを直せないか考える。直せるなら直す。
コメントは少ないほうがいいのではなく、嘘をつかないものだけが残ればいい。