6章 コメントは正確で簡潔に
本章では、コメントを正確で簡潔に書く方法について説明する。
あいまいな代名詞を避ける
//データをキャッシュに入れる。ただし、先にそのサイズをチェックする。
「その」が指しているものは、「データ」かもしれないし「キャッシュ」かもしれない。
紛らわしいので代名詞の使用は避けるべきである。
//データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。
関数の動作を正確に記述する
//ファイルに含まれる行数を返す
function countLines(fileName) {
...
}
「行」にはさまざまな意味があり、このコメントだけでは関数の正確な動作がわからない。
例えば、"hello\n"は、1行なのか2行なのか？
この関数が改行文字\nの数をカウントするのだとしたら、以下のようなコメントの方が適切だ。
//ファイルに含まれる改行文字(\n)を数える。
function countLines(fileName) {
...
}