ブログトップ 記事一覧 ログイン 無料ブログ開設

Strategic Choice

2014-09-03

[]コメント:情報密度の濃さ:実例を使う

どういうこと?

コメントには、実例を書くようにします。特に入出力の実例は有効です。

どうして?

具体例は「千の言葉」に等しい価値があります。

例えば、文字列の一部を除去する関数があるとします。

// 'src' の先頭や末尾にある'chars' を除去する。
String Strip(String src, String chars) { ... }

このコメントでは、以下のような質問に答えることができません。

  • 「chars」は、除去する文字列なのか、順序のない文字集合なのか?
  • 「src」の末尾に複数のchars があったらどうなるのか?

これは、具体的な例がないからです。

どうすれば?

コメントには、具体例を書くようにします。特に、入出力のコーナーケースの実例は役に立ちます。

上述例であれば、以下のように修正します。

// ...
// 実例:Strip("abba/a/ba", "ab") は"/a/" を返す
String Strip(String src, String chars) { ... }

この実例は、Strip() のすべての機能を見せています。

もう一つ別の例で考えてみます。

// 'v' の「要素 < pivot」が「要素 >= pivot」の前に来るように配置し直す。
// それから、「v[i] < pivot」になる最大の'i' を返す(なければ-1 を返す)。
int Partition(vector<int>* v, int pivot);

このコメントは実に正確です。しかし、視覚的に多少難しくなっています。実例を使ってより詳しく説明してみます。

// ...
// 実例:Partition([8 5 9 8 2], 8) の結果は [5 2 | 8 9 8] となり、1 を返す。
int Partition(vector<int>* v, int pivot);

この実例には、大切な点がいくつかあります。

  • pivot をベクタの要素と同じにして、エッジケースを示している。
  • ベクタに重複要素(8)を入れることで、これが入力値として受け入れられることを示している。
  • 結果のベクタはソートしていない。ここでソートしていたら、ソートされているはずと読み手が誤解する可能性がある。
  • 戻り値が1 になるので、ベクタの要素に1を入れていない。

2014-09-02

[]コメント:情報密度の濃さ:正確に書く

どういうこと?

コメントで、関数の動作を「正確に」伝えるようにします。

どうして?

コメントが正確でないと、解釈にブレが生じます。

たとえば、ファイルの行数を数える関数を書いているとします。

// このファイルに含まれる行数を返す。
int CountLines(string filename) { ... }

これは、あまり「正確な」コメントではありません。「行」にはさまざまな意味があるからです。コーナーケースを考えてみます。

  • ""(空のファイル)は、0行なのか1行なのか。
  • "hello" は、0行なのか1行なのか。
  • "hello\n" は、1行なのか2行なのか。
  • "hello\n world" は、1行なのか2行なのか。
  • "hello\n\r cruel\n world\r" は、2行なのか3行なのか4行なのか。

どうすれば?

関数の動作のコメントは、その解釈が一つになるよう、正確に記述します。

上述例の「ファイルの行数を数える関数」であれば、最も単純な実装は、改行文字(\n)を数えるものです*1。この実装に適したコメントは、以下のようになります。

// このファイルに含まれる改行文字('\n')を数える。
int CountLines(string filename) { ... }

最初のコメントと比較すると、それほど長くはなっていないのに、伝わる情報は格段に増えています。改行文字がない場合は、0を返すことがわかります。また、キャリッジリターン(\r)が無視されることもわかります。

*1:Unixのwcコマンドの実装です。

2014-09-01

[]コメント:情報密度の濃さ:直接的に書く

どういうこと?

コメント中の「歯切れの悪い」文章は、より直接的な表現に変更します。

どうして?

コメントをより直接的な表現にすると、「正確にすること」と「簡潔にすること」が両立した、よいコメントになります。

どうすれば?

歯切れの悪い文章を、より直接的な表現に変更して、正確さと簡潔さの両方を満たします。

以下は、ウェブクローラのコメント例です。

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

この文章は問題なさそうに見えます。しかし、以下と比較してみると、考えが変わります。

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

こちらのほうが「単純」だし「短い」し「直接的」です。さらには、「クロールしていないURLの優先度が高い」という、先のコメントでは言及されていない情報も含まれています。

2014-08-29

[]コメント:情報密度の濃さ:代名詞を避ける

どういうこと?

あいまいな代名詞は物事を複雑にしてしまうので、コメントには使用しません。

どうして?

代名詞は、読み手が「還元」しなければなりません。その際、「それ」や「これ」が何を指しているのか、よくわからないこともあります。

たとえば、以下のコメントです。

// データをキャッシュに入れる。ただし、先にそのサイズをチェックする。

「その」が指しているのは、「データ」かもしれないし「キャッシュ」かもしれません。おそらく、コードを読み進めていけば、どちらを指しているのかわかります。でも、そうしないとわからないのであれば、コメントの意味がありません。

どうすれば?

代名詞は避け、名詞を使用します。

上述の例であれば、「それ」を「データ」に変えます。

// データをキャッシュに入れる。ただし、先にデータのサイズをチェックする。

あるいは、文章全体を書き換えて「それ」を明確にすることもできます。

// データが十分に小さければ、それをキャッシュに入れる。

2014-08-28

[]コメント:情報密度の濃さ:簡潔にする

どういうこと?

コメントは簡潔にします。

どうして?

コメントは画面の領域を取るし、読むのにも時間がかかるので、簡潔なものでなければいけません。

どうすれば?

コメントを簡潔にして、時間と空間を節約します。

例えば、以下は、型定義につけたコメントです。

// int はCategoryType。
// pair の最初のfloat は'score'。
// 2 つめは'weight'。
typedef hash_map<int, pair<float, float> > ScoreMap;

これなら1 行で説明できます。

// CategoryType -> (score, weight)
typedef hash_map<int, pair<float, float> > ScoreMap;