第5章:コメントすべきことを知る
概要
コメントをすべきであるということと、コメントの目的が、書き手の意図を読み手に知らせるということであることを伝えている。また、コメントの機能である「コードの動作を説明すること」はコメント機能のごく一部でしかないことを伝えている、加えて、説明は「コメントすべきではないことを知る」「コードを書いている時の自分の考えを記録する」「読み手の立場になって何が必要になるかを考える」という3つの着眼点から貝瀬接してくれている。
まとめ
・コメントの目的は、「コードの意図を読み手に理解してもらうこと」である。
・とにかくまずは、コメントを書いてみる。そこから、抽象的なことを書いているのであれば、具体的に書き直せばいい。
・「記録すべきではないことは書かない」「記録すべき自分の考える」「読み手の立場になって考える」これらが本章では大事である。
学んだ点
・コメントには、そのコメントを読むだけの価値を持たせるべきである。要するに、本来コードを読むことが多いにもかかわらず、コメントも書くと読むべきものが多くなりすぎるということ。
・すぐにわかるようなことは書くと無駄になるだけ
・コメントは、ひどい変数名を解説するために使うべきではない。
・関数等の命名でその関数等が自身を説明できるのであれば、わざわざコメントする必要はない。それを簡単に表せるのは、「優れたコード > ひどいコード + 優れたコメント 」
・優れたコメントは「考えを記録する」ためのものである。
・コード作成中によく使う記法について、「TOTDO 意味:後で手を入れる」「FIXME 意味:既知の不具合があるコード」「HACK 意味:あまり綺麗じゃない解決案」「XXX 意味:大きな問題点あり」等を用いる。
・これからコードをどうしたいかを考えてコメントを残しておき、解決の方向性を共有する。
・定数の値を決めた時に頭の中で考えていたことを記録することが大切である。
・自分よりもそのプロジェクトを理解していない人のためにコメントを書く必要がある。そのためには、「質問されそうなことを想像すること」や「ハマりそうな罠を告知すること」、「全体像のコメントをすること」、「要約コメントをすること」が重要である。
・「全体像のコメントをすること」がなぜ重要かというと、プロジェクトにアサインされてコードを読み進める際に、どのようにクラスとクラスがつながっているのか把握する時間的コストが高いためである。
・ライターズブロックを乗り越える。そのために、とりあえず思っていることをコメントに書いてみる。そして、その後に抽象的なことがあるとわかれば、具体的に誰でもわかるように編集すればいい。とにかく、コメントしてみることが大事である。
感想と振り返り
自身の時間ベースで、「コメントをしたら行が増えて読みにくいんじゃないか？」と考えることが多かった。しかし、むしろ逆でどのような意図で書いたかを理解してもらうことが目的なのであれば、コメントを1、2行増えることは大したことないということを学べました。
また、今後実装をどんどん進めていくと思いますが、その際はのちにアサインされた人がコードの意図をすぐに理解できるようなコメントや変数を記述していきたいですね！