06章『コメントは正確で簡潔に』

どうすればコメントを正確に書けるか

ポイント

コメントは領域に対する情報の比率が高くなければならない

 

6.1 コメントを簡潔にしておく(P.72)

そのコメントは１行でまとめられないか？　と自問する

6.2 あいまいな代名詞を避ける(P.72)

読み手は「代名詞」を還元しなければならない。

コメントを理解するためにコードを読み進めなければいけないのは本末転倒。

 

6.3 歯切れの悪い文章を磨く(P.73)

コメントを正確にすること　＝　簡潔にすること

×　// これまでにクロールしたURLかどうかによって優先度を変える

〇  // これまでにクロールしていないURLの優先度を高くする

 

6.4 関数の動作を正確に記述する(P.73)

×　// このファイルに含まれる行数を返す

〇  // このファイルに含まれる改行文字（′\n'）を数える

 

"　"は１行として数えないことが分かる

 

6.5 入出力のコーナーケースに実例を使う(P.74)

×　// 'src'の先頭や末尾にある'chars'を除去する

〇  // 実例：Strip("abba/a/ba", "ab")は"/a/"を返す

String Strip(String src, String chars) {...}

 

6.6 コードの意図を書く(P.76)

コードの動作を書くだけではだめ

×　listを逆順にイテレートする

〇　値段の高い順に表示する

 

6.7 「名前付き引数」コメント（P.77）

void Connect(int timeout, bool use_encryption) {...}

// 引数にコメントをつけて関数を呼び出す

Connect(/* timeout_ms = */ 10, /* use_encryption = */ false) ;

 

6.8 情報密度の高い言葉を使う(P.78)

・キャッシュ層

・正規化

・ヒューリスティック

など

 

6.9 まとめ(P.78)

・複数のものを指す可能性がある「それ」や「これ」などの代名詞を避ける。

・関数の動作はできるだけ正確に説明する。

・コメントに含める入出力の実例を慎重に選ぶ。

・コードの意図は、詳細レベルではなく、高レベルで記述する。

・よくわからない引数にはインラインコメントを使う

　（例：Function(/* arg = */ ...)）

・多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔に保つ。

 

担当：やし