リーダブルコードを読む part6
こんにちはかわです。
アドベントカレンダー21記事目です。
前回の続きです。
6章 コメントは正確で簡潔に
コメントは領域に対する情報の比率が高くなければならない
1 コメントを簡潔にしておく
少ない領域ですむように推敲する
2 曖昧な代名詞を避ける
代名詞はなるべく避けるように努める。
代名詞が何を指すかを明確にすべし。
3 歯切れの悪い文章を磨く
語彙力を磨く
4 関数の動作を正確に伝える
なるべく詳細に伝える。
コメントを読む人の誤解を減らすため。
5 入出力のコーナーケースに実例を使う
コメントが長文になる際には実例を使うべし。
ただし、簡単な実例では役に立たないので、
想定される質問に応えられる実例を書く。
6 コードの意図を書く
コードの動作をそのまま書くのではなく、高レベルから説明するのもあり。
その結果、コードが作者の意図に反しているかどうか見つけやすくなる。
7 「名前付き引数」コメント
これはコメントのような効果があるため使ったほうがいい。
Connect(/* timeout_ms */ 10);
8 情報密度が高い言葉を使う
説明が長くなった場合、専門用語等を使用して短くできないか検討する。