本書の第１部「表面上の改善」にある6章のサマリーをまとめる。
（編集途中です）
コメントは領域に対する情報の比率が高くなければいけない
6.1 コメントを簡潔にしておく
1行で説明できることを、3行も使わない。
6.2 あいまいな代名詞を避ける
代名詞は物事を複雑にする。
読み手は代名詞を「還元」しなければならず、場合によって「それ」や「これ」が何を指すのかよくわからないこともある。
最も簡単な改善は、名詞を代名詞に代入すること。
または文章全体を書き換えて代名詞を明確化できる。
6.3 歯切れの悪い文章を磨く
コメントを正確にすることと簡潔にすることは両立する。
単純で短くて直接的なコメントがいい。
6.4 関数の動作を正確に記述する
実装に適したコメントは伝わる情報を格段に増やす。
6.5 入出力のコーナーケースに実例を使う
慎重に選んだ入出力の実例をコメントに書いておけば、千の言葉に等しい。
6.6 コードの意図を書く
コメントはコードを書いているときに考えていたことを読み手に伝えるためのもの。
でも、コードの動作をそのまま書いているだけで何も情報を追加していないコメントが多い。
プログラムの動作を高レベルから説明するといい。
すると、コメントが冗長検査の役割を果たしうる。
6.7 「名前付き引数」コメント
インラインコメントを使って引数を名前付きで渡せば、引数をわかりやすくできる。
6.8 情報密度の高い言葉を使う
コメントが長くてくどいと感じたら、問題や解決策のパターンやイディオムを説明するための言葉や表現を使えないか確かめる。
6.9 まとめ
- 複数のものを指す可能性のある「それ」や「これ」などの代名詞を避ける
- 関数の動作はできるだけ正確に説明する
- コメントに含める入出力の実例を慎重に選ぶ
- コードの意図は、詳細レベルではなく高レベルで記述する
- よくわからない引数にはインラインコメントを使う（
Function(/* arg = */ ... )など） - 多くの意味が詰め込まれた言葉や表現を使ってコメントを簡潔に保つ