リーダブルコード 第5・6章はコメントについて。
今回はコメントです。ここは結構賛否両論になるところではないかと思います。
ざっくり分けると「できるだけコメントは詳しく書くこと」という意見と「コメントはなるべくかかない(コメントを書く必要がないくらいコード自体をわかりやすくしろ)」という意見が多いですね。もちろん一番大切なのはバランスなんですが・・・
リーダブルコードでは両方の立場(書くべきでないコメントと書くべきコメント)からの意見が書かれています。
Contents
目的は読み手が理解しやすいかいなか
そもそもコメントの目的としては読み手にとって読みやすい、書き手に誤解されない、ということが重要です。コメント自体はこれを実現するための手段になります。
なんでもかんでもコメントを書いていると、コードが長くなり、コードを読む行為が増えますので、その分だけ読み手に負担をかけます。
逆に少なすぎれば当然、情報を得るのに必要な時間・労力を読み手に与えることになります。
読み手の立場に立って考えることが大切になってくるわけです。
当たり前のことをコメントにかかない
例えばコンストラクタにこれはコンストラクタ、みたいなコメントですね。読めばわかるようなことはわざわざコメントしないということですね。
コメントが冗長になりすぎる場合は命名変更を考える
コメントが冗長になりすぎる場合はコメントを減らすことになりますが、まずは命名を変えられないか、と考えてみましょう。要はコメントではなく、名前から情報を伝えようということです。
考えの記録を書く
コードを書くときの大切な考えを記録しておきます。
映画監督のコメントのように → 注意しておきたい情報や気づきなど
コードの欠陥 → あとあと必要な修正や問題点など
読み手がはまりそうなポイントを書く
間違えやすいことや起きやすいバグなどについて。通常だったらAという方法をとるのになぜわざわざAじゃない方法をとっているのか、など。
全体像を説明する
クラスの一番上や大きなメソッドには箇条書きだったり、全体として何をするべきものかというのを要約しておきましょう。
簡潔かつ、わかりやすいもの
これはコードと同じなのですが、同じ情報量だったら簡潔なもののほうがよいです。なるべく短くできないか、文書よりは式や記号的なもので代用できないかを考えましょう。
意味不明な代名詞を使わない
あれ、これ、それ、どれといった何を指すのかがわからないものは読み手に混乱を与えるのでやめましょう。
具体性のあるコメントにする
コードと同じなのですが、意味がぼやけていて、解釈の仕方がわかれるようなものではなく、具体性のある記述にしましょう。
実例を書く
メソッドのコメントなどは言葉で説明するより、具体例で説明したほうがわかりやすいでしょう。
