本書の第１部「表面上の改善」にある5章のサマリーをまとめる。
（編集途中）
コメントの目的は、書き手の意図を読み手に知らせることである
5.1 コメントするべきでは「ない」こと
コメントを読むとその分だけコードを読む時間がなくなる。
コメントは画面を占領してしまう。
つまり、コメントにはそれだけの価値を持たせるべき。
コードからすぐにわかることをコメントに書かない
コメントのためのコメントをしない
コメントを付けたければ、大切なことを説明した方がいい。
ひどい名前はコメントをつけずに名前を変える
優れたコメントより名前の方が大切。関数名を「自己文書化」する。
優れたコード > ひどいコード + 優れたコメント
5.2 自分の考えを記録する
優れたコメントは「考えを記録する」ためのもの。
「監督のコメンタリー」を入れる
コメントにはコードに対する大切な考えを記録しなければいけない。
コードが汚い理由をコメントに書いてもいい。
コードの欠陥にコメントをつける
コードは絶えず進化するので、その過程で欠陥を生む運命にあり、それを文書化することを恥ずかしがってはいけない。
プログラマがよく使う記法がいくつかある。
|記法 |典型的な意味 |
|---|---|---|
|TODO: |あとで手をつける |
|FIXME: |既知の不具合があるコード |
|HACK: |あまりキレイじゃない解決策 |
|XXX: |危険！大きな問題がある |
大切なのは、これからコードをどうしたいのかを自由にコメントに書くこと。
そういうコメントを書くことで、コードの品質や状態を知らせたり、さらには改善の方向を示したりできる。
定数にコメントをつける
定数を定義するときには、その定数が何をするのか、なぜその値を持っているのかという「背景」が存在する場合が多い。
定数の値を決めたときに頭の中で考えていたことを記録することが大切。
5.3 読み手の立場になって考える
どこにコメントをつければいいか判断するのに、「他の人」（プロジェクトのことを君のように熟知していない人）にコードがどのように見えるか想像する必要がある。
質問されそうなことを想像する
他人が疑問を持つようなところにコメントをつければいい。
ハマりそうな罠を告知する
関数やクラスを文書化するときには、「このコードを見てびっくりすることは何だろう？ どんなふうに間違えて使う可能性があるだろう？」と自問するといい。
ユーザが使った「あと」に気づくよりも、使う「前」に告知する方がいい。
「全体像」のコメント
新しくチームに参加した人に、ソースコードを読んだだけでは得られない情報を高レベルのコメントとして書くべき。
短い適切な文章で構わない。ないよりまし。
要約コメント
関数の内部でも「全体像」についてコメントする。低レベルのコードをうまく要約したコメントがよい。
5.4 ライターズブロックを乗り越える
ライターズブロック（行き詰まってしまって、文章が書けないこと）を乗り越えるには、とにかく書き始めるしかない。自分の考えていることをとりあえず書き出す。
コメントを書く手順は
- 頭の中にあるコメントをとにかく書き出す
- コメントを読んで（どちらかと言えば）改善が必要なものを見つける
- 改善する
早めにしょっちゅうコメントを書いていけば、最後にまとめて大量のコメントを書くような事態に陥ることはない。
5.5 まとめ
コメントすべきではないこと：
- コードからすぐ抽出できること
- ひどいコードを補う補助的なコメント。コメントを書くのでなくコードを修正する
記録すべき自分の考え：
- なぜコードが他のやり方ではなくこうなっているのか
- コードの欠陥を示す
- 定数の値にまつわる背景
読み手の立場になって考える：
- コードを読んだ人が「えっ？」と思うところを予想してコメントをつける
- 平均的な読み手が驚くような動作は文書化しておく
- ファイルやクラスには「全体像」のコメントを書く
- 読み手が細部に捕われないように、コードブロックにコメントをつけて概要をまとめる