第5章 コメントすべきことを知る

• 読み手が細部に捕らわれないように、コードブロックにコメントつけて概要を書く

• ファイルやクラスには全体像のコメントを書く

• 定数の値にまつわる「背景」を書く
  なぜこの値になったかを書く。

• 平均的な読み手が驚くような動作は文章化してコメントとして書く
  なんでこんな処理しているんだろうと疑問に思いそうなところに書く。

• コードを読んだ人が疑問って思うところを予想してコメントを書く

• なぜコードがこうなっているのかを書く(監督コメンタリー)
  他のやり方(ロジック等)でなくこうなっているかを書く。

• コードの欠陥をTODO:やXXX:などの記法を使って表す

記法	意味
TODO	あとで手を付ける
FIXME	既知の不具合があるコード
HACK	あまりきれいじゃない解決策
XXX	危険！大きな問題がある

補足
コメントすべきではないこと
・コードを読めば理解できる内容
・ひどいコード(例えばひどい関数名)を補う「補助的なコメント」
その場合はコメントではなくコードを直す。

所感

今まで書いていたコメントは、コードの内容を記載して重要な情報が不足していたように感じる。
上記のポイントを意識して書く訓練を行う。