「コメントを多めに」と頼んだコードは、本当に読みやすいか

先に問いを分ける：量・種類・正しさ

「コメントが多いと読みやすいか」は、実は三つの問いが重なっています。

• 量：行数が増えると、理解は速く正確になるか。
• 種類：コメントには、コードが何をしているかを書く「what」、なぜそうしているかを書く「why」、コードの言い換えにすぎないもの、使う際の注意の4種類があります。増えたのはどれか。
• 正しさ：コメントの内容はコードと食い違っていないか。食い違っていれば、読者はコメントを信じて誤解します。

実験の主役は「量」ですが、量だけを見ると結論を誤りやすくなります。「多め」と頼んでも、増えるのが言い換えばかりなら、理解の助けにはならない可能性があります。逆に、少ないコメントでも why が一行あるだけで足りることもあります。記録では量と種類を必ず分けて数えます。

もう一点、AIはそのコードを書いた人の意図を知りません。why を書けと言われても、推測で書くことになります。この点は第4の条件で扱います。

準備：コメントなしの元コードと4つの条件

元コード

題材は、ジャンプ処理です。コヨーテタイム（足場から離れた直後の数フレームも、ジャンプを受け付ける仕組み）と、ジャンプバッファ（着地の少し前に押した入力を覚えておく仕組み）を含みます。コメントは一切入れていません。地面は y=0 で、上向きは負の値です。

const GRAVITY = 0.4;
const COYOTE_FRAMES = 6;

function createPlayer() {
  return { y: 0, vy: 0, onGround: true, coyote: 0, jumpBuffer: 0 };
}

function update(p, input) {
  if (input.jumpPressed) p.jumpBuffer = 5;
  else if (p.jumpBuffer > 0) p.jumpBuffer--;

  if (p.onGround) p.coyote = COYOTE_FRAMES;
  else if (p.coyote > 0) p.coyote--;

  if (p.jumpBuffer > 0 && p.coyote > 0) {
    p.vy = -8;
    p.coyote = 0;
    p.jumpBuffer = 0;
    p.onGround = false;
  }

  p.vy += GRAVITY;
  p.y += p.vy;
  if (p.y >= 0) { p.y = 0; p.vy = 0; p.onGround = true; }
}

4つの条件

このコードをAIに渡し、条件ごとに別の依頼文でコメントだけを付けさせます。どの条件でも「コードの文字は一切変えず、コメントだけを追加してください」と添えます。

• A、依頼文の要点：コメントなしの元コードのまま
• B、依頼文の要点：「コメントを多めに付けてください」
• C、依頼文の要点：「コメントは必要最小限にしてください」
• D、依頼文の要点：開発者のメモ（なぜ6フレームか、なぜジャンプ後に coyote を0にするか等、読者自身が決めた意図）を添えて「コメントを付けてください」

条件Dの意図メモは、読者自身が考えた理由を使います。AIの出力から借りると、推測が正解のように混ざります。

コード不変の確認

各条件の出力を元コードと差分比較し、コメント以外の差分がないことを確認します。AIが親切心で変数名を変えたり、処理を整理したりすることがあるためです。コードが変わっていれば、それはコメントの実験ではなくなります。変わっていた条件は作り直し、作り直した回数も記録します。

手順と記録の取り方

正解を先に機械で確定する

理解テストの正解は、記憶や推測ではなく、実行して決めます。たとえば次のハーネス（検証用の短いコード）で、足場を離れてから何フレーム後までジャンプが成立するかを確かめられます。

function jumpableAfter(n) {
  const p = createPlayer();
  p.coyote = COYOTE_FRAMES;
  p.onGround = false;
  p.y = -1000;
  for (let i = 0; i < n; i++) update(p, { jumpPressed: false });
  update(p, { jumpPressed: true });
  return p.vy < 0;
}
for (let n = 0; n <= 10; n++) console.log(n, jumpableAfter(n));

ログで true から false に切り替わる境目が、質問1の正解です。コメントや名前から想像した値と一致するかは、ここで初めて分かります。

質問票（5問）

1. 足場を離れたあと、何フレーム目までジャンプ入力が有効ですか（上のハーネスで確定）。
2. 着地の何フレーム前に押したジャンプ入力が、着地と同時のジャンプになりますか（ハーネスを書き換えて確定）。
3. ジャンプ成立時の p.coyote = 0 を消すと、何が起こりえますか。
4. 先行入力の受付を5フレームから8フレームに変えるには、どこを直しますか。
5. このコードで、ジャンプが「出ない」と報告された場合に最初に疑う変数はどれですか。

質問の言葉は、コメントの文面と一致させないでください。一致すると、理解ではなくコメントの検索になります。

読む順序

同じ人が同じコードを複数の条件で読むと、記憶が残ります。次のどちらかで進めます。

• 簡易版：条件ごとに別の人が読む。1条件につき最低2人は集めます。
• 拡張版：同程度の長さで、why が要る短い関数を3つ用意し（弾のクールダウン、コンボ加算など）、条件と題材の組み合わせを参加者ごとに入れ替える。

記録するもの

1人・1条件・1題材を1行として、次の項目を残します。

• 条件（A〜D）、記録の単位：記号
• コメント比率、記録の単位：コメント行数 ÷ 全行数
• コメントの内訳、記録の単位：what／why／言い換え／注意の各件数
• コメントの誤り、記録の単位：コードと食い違う件数
• 質問1〜5の正誤、記録の単位：問ごとに○×（5問中の正答数）
• 所要時間、記録の単位：読み始めから最後の回答まで、秒
• 変更課題の結果、記録の単位：質問4の修正が動作を壊さなかったか
• 迷った箇所、記録の単位：自由記述

時間は読み始めと回答完了をそろえて測ります。コメントの分類は、読者本人ひとりで決めると偏ります。可能なら別の人が独立に分類し、食い違った件は話し合って決めます。

結果の読み方

記録がそろったら、条件ごとに正答数と時間を並べます。次の表は判断の目安です。

• Bの正答が上がり、時間も短い、読み方：多めのコメントが助けている可能性、次の一手：内訳を見て、増えたのが why か what かを確かめる
• Bの正答は同程度で、時間だけ長い、読み方：読む量が増えただけの可能性、次の一手：Cとの差を内訳で確認する
• どの条件も差が小さい、読み方：この題材では変数名が十分に説明的で、差が出ていない可能性、次の一手：題材を変えて再度確かめる
• 誤ったコメントを信じた誤答がある、読み方：量より正しさが効いている、次の一手：コメントの誤り件数と誤答の対応を調べる
• Dだけ正答が高い、読み方：意図の情報が効いている可能性、次の一手：意図をコメントでなく別の形（README等）で残す案も検討する

この実験は人数が少なくなりがちなので、結果は確定ではなく傾向として読みます。1問の誤差で順位が入れ替わる規模です。数値の大小より、内訳（何が増えたか、どこで間違えたか）を重視してください。

起こりやすい誤り

• コードが変わっている：AIが変数名や処理を整理していることがあります。差分確認を省かないでください。
• 1回の生成で判断する：同じ依頼でも出力は毎回変わります。余裕があれば同じ条件で複数回生成し、コメント比率と内訳のばらつきも記録します。
• 量と種類が混ざる：「多め」の条件で why が増えたとは限りません。内訳を数えずに「多いほど良い」と結論するのが最も多い誤りです。
• 質問がコメントの文面に寄る：答えがコメントに書かれていれば、理解ではなく検索を測ることになります。
• 読み手の予備知識：コヨーテタイムを知っている人は、コメントなしでも読めます。予備知識の有無も、参加者ごとに記録します。
• 正解を推測で決める：質問1と2は必ず実行して確定します。作問者の思い込みがそのまま採点基準になるのを防げます。

次の行動

まず元コードを自分の手元に置き、ハーネスで質問1の答えを確定してください。次に、条件BとCの依頼文でコメントを付けさせ、差分で「コメント以外が変わっていないか」を確かめます。ここまでで、コメントの比率と内訳を数えるだけでも、「多め」が何を増やすのかが見え始めます。