コードにコメントすべきこと
created : / updated :
コメントの目的
コメントの目的は、書き手の意図を読み手に知らせることである。
コードを理解するのに役立つものならとりあえず書いておくのがよい。
コメントしなくてもいいこと
コードからすぐに分かることはコメントに書かない
コメントを書けば行数が増える。すなわちコード量が増えるということであり、新しい情報を提供しないコメントは価値がなく、不要である。
適切に責務を分離して小さくメソッドを作るようにしたら、そもそもコメントが必要にならない場合もある。前提として、コメントが無くても理解できるコードが理想である。
自分の考えを記録する
ここはこういう考えでこういう記述をした、というコメントを残しておく。
コードを読めば何をやっているかは分かっても、何のために何でその実装なのかは分からない。初見のソースコードでは、Why を記したコメントが道標となる。
読み手の立場になって考える
コードを書き終えた後に、そのコードを初めて読む人の視点でコードを読み直してみる。そこで疑問に思いそうなこと、勘違いしそうなことがあったら、コメントを残しておくのがよい。コードを理解するための前提、またはコードがやっていることの要約を書くことが多い。
コメントは簡潔に
明確に、簡潔に。