「他の人も読めるように」と一言足すと、AIのコードは何が変わるのか：比較実験の設計書

問いを一つに絞る

最初に、検証する問いを一文で決めます。広げすぎると、結果を読むときに何も言えなくなります。

同じゲームの依頼文の末尾に「他の人も読めるようにしてください」を足すと、コードの構造と読みやすさは、足さないときと比べて変わるか。

この問いには、変わりうる点が少なくとも3つあります。

• 書き方の表面：コメントの量、変数名や関数名の付け方
• 構造：関数の分け方、定数の切り出し方、処理の並べ方
• 読み手の体験：初めて読む人が、知りたい箇所をどれだけ早く見つけられるか

1つめだけ変われば、一言は「飾り」を増やす効果にとどまります。2つめ、3つめまで動いて初めて、一言が「読み手を想定した設計」に届いたと言えます。記録の段階で、この3層を分けて見られるようにしておきます。

準備するもの

次のものを用意します。

1. 依頼するゲームを1本決めます。 小さく、ルールが明確なものが向いています。たとえば、制限時間30秒で、ミスが3回に達すると終わる「もぐらたたき」です。複雑なゲームだと、出力の差が依頼内容の解釈違いに紛れてしまいます。
2. 依頼文を2種類つくります。 条件Aは基本の依頼文、条件Bは条件Aの末尾に一言を足しただけの文です。他の語は1文字も変えません。
3. 余裕があれば条件Cも用意します。 条件Cは、一言の代わりに具体的な指示（「定数は先頭にまとめる」「処理は関数に分ける」など）を足した文です。曖昧な一言と具体的な指示の差を見るための対照になります。
4. 出力形式を固定します。 「1つのHTMLファイルで、外部ライブラリなし」のように、全条件に共通で入れます。アソバースへ投稿する前提なら、「入口は直下のindex.html、素材は相対パス」という条件も共通部分に入れておくと、そのまま作品の形になります。
5. 会話は毎回新しく始めます。 前の会話が残っていると、前回の出力が次の回に影響します。
6. 記録用の表と、後で紹介する計測ページを用意します。

依頼文の例は次のとおりです。

• 条件A：「ブラウザで動く、1ファイルのHTMLで『もぐらたたき』を作ってください。制限時間は30秒、ミスは3回までです。」
• 条件B：条件Aの文に「他の人も読めるようにしてください。」を続けたもの
• 条件C：条件Aの文に「定数は先頭にまとめ、処理は役割ごとの関数に分け、各関数の前に一行で目的を書いてください。」を続けたもの

手順と記録の取り方

条件ごとに最低5回、合計で10〜15回の生成を行います。1回だけでは偶然との区別がつかないからです。AIの出力は毎回少しずつ揺れるので、5回並べて初めて「揺れの幅」が見えます。

順序は、A・B・A・B…と交互にするか、くじで決めます。Aを5回続けてからBを5回続けると、時間帯や利用状況による差が条件の差に混ざる可能性があります。

各回の出力は、次のように扱います。

1. コードをそのままファイルに保存します。手で直したり、不要部分を削ったりしません。
2. ファイル名は「A-1」「B-3」のような符号にします。後で読み比べるときに、条件が分からない状態にしやすくなります。
3. 動くかどうかを一度確かめ、記録に「動作：○／×」を書きます。動かない出力も捨てません。一言が動作の安定性に影響する可能性もあるからです。

記録表は次の形にします。

• A-1、動作：、空行を除く行数：、コメント行数：、定数の数：、0と1以外の数字の直書き：、関数の数：、目的の箇所を探せた秒数：

「0と1以外の数字の直書き」は、3 や 30000 のように意味の分からない数がコード中に埋まっている数です。プログラミングでは「マジックナンバー」と呼ばれ、後から読む人が最もつまずきやすい要素の一つです。

数える作業を半自動にする

行数やコメント数を目で数えると、数え間違いが起きます。次の小さなページに出力を貼れば、粗く数えられます。HTMLファイルとして保存してブラウザで開くだけで動き、外部通信はありません。

<!doctype html>
<meta charset="utf-8">
<textarea id="src" rows="12" cols="60" placeholder="ここにコードを貼ります"></textarea>
<br><button id="go">数える</button>
<pre id="out"></pre>
<script>
document.getElementById("go").onclick = () => {
  const text = document.getElementById("src").value;
  const lines = text.split("\n").filter(l => l.trim() !== "");
  const isComment = l => /^\s*(\/\/|\/\*|\*|<!--)/.test(l);
  const isConst = l => /\bconst\s+[A-Z][A-Z0-9_]*\s*=/.test(l);
  const comments = lines.filter(isComment).length;
  const consts = lines.filter(isConst).length;
  const body = lines.filter(l => !isComment(l) && !isConst(l)).join("\n");
  const magic = (body.match(/(?<![\w.$"'#])\d+(\.\d+)?(?![\w"'])/g) || [])
    .filter(n => n !== "0" && n !== "1").length;
  const funcs = (text.match(
    /\bfunction\s+\w+|\b\w+\s*=\s*(\([^)]*\)|\w+)\s*=>/g) || []).length;
  document.getElementById("out").textContent =
    "空行を除く行数: " + lines.length +
    "\nコメント行数: " + comments +
    "\n大文字名の定数: " + consts +
    "\n数字の直書き(0,1以外): " + magic +
    "\n関数の数(概数): " + funcs;
};
</script>

このページは正規表現で数えるだけなので、精度には限界があります。CSSの数値や文字列中の数字を拾うことがありますし、定数を小文字で書くコードは「定数」に数えられません。ここで見るのは絶対値ではなく、同じ道具で数えた条件間の相対的な差です。気になる出力は、目でも確かめてください。

数字では測れない部分を、読み手の目で測る

行数やコメント数が増えても、読みやすくなったとは限ります。コメントが多くても、「ここで1を足す」のようにコードの言い換えにすぎない場合があります。そこで、数えた指標とは別に、読み手の体験を測る小さな課題を用意します。

出力した全ファイルに、同じ質問を3つ投げます。

1. 制限時間を30秒から45秒に変えるには、どこを直せばよいか。
2. ミスの上限を3回から5回に変えるには、どこを直せばよいか。
3. もぐらが出てくる間隔を調整する処理は、どこにあるか。

各ファイルについて、答えの場所を見つけるまでの秒数を記録します。注意点は次のとおりです。

• 符号だけを見て読みます。 どの条件のファイルかを知ったまま読むと、期待が秒数に影響します。ファイルをシャッフルして渡してもらえる協力者がいれば理想的です。
• 同じ人が全ファイルを読むと、慣れが生じます。 ゲームの構造を覚えてしまい、後半ほど速くなります。順序をランダムにするか、読み手を2人以上にして、結果を並べます。
• コードを書き慣れた人と、ほとんど書かない人では、読み方が違います。 想定読者に近い人に頼むほうが、結果が実用に近づきます。

協力者がいない場合は、自分でやってもかまいません。ただし、その場合は読む順序を必ずくじで決め、1日あけて読むなど、記憶の影響を減らします。それでも一人での実験には偏りが残ることを、結論に書き添えます。

結果の読み方

5回ずつの値が集まったら、条件ごとに最小値と最大値を並べます。平均だけを出すと、揺れの大きさが見えなくなります。

判断の基準は次のとおりです。

• 条件AとBの範囲が重なっている：この依頼とこの回数では、一言の効果は偶然と区別できません。回数を増やすか、ゲームを替えて追試します。
• 範囲が重ならず、方向が揃っている：一言が何かを動かした可能性があります。ただし、5回ずつは小さな標本です。「この環境では差が見えた」と書くにとどめ、一般化は避けます。
• 指標はBが大きく、探した秒数は変わらない：書き方の表面が変わっただけで、読み手の体験には届いていない可能性があります。コメントは増えたが、探す手間は減っていない状態です。
• 指標の差は小さいが、探した秒数が短い：数えられない部分、たとえば名前の付け方や処理の並び順が効いている可能性があります。実際のコードを見比べて、どこが違うかを具体的に書き出します。
• 条件Cだけが大きく動く：曖昧な一言ではなく、具体的な指示が必要だったという読み方ができます。「読めるように」という願いを、どんな行動に翻訳するかを書かないと、AIは動きにくいのかもしれません。

もう一つ見てほしい指標が、動作の安定性です。一言を足したことで、動かない出力が増えていないかを確認します。読みやすさを意識した結果、機能が欠ける可能性もあるからです。

起こりやすい誤り

この実験で崩れやすい点を挙げます。

1. 一言以外の差が混ざる。 条件Bを書くときに、うっかり言い回しを直してしまう例です。コピーして末尾にだけ足す手順にします。
2. 出力の長さの差を、構造の差と取り違える。 行数が増えれば、コメントも関数も自然に増えます。数は「行数あたり」に直して比べると、取り違えにくくなります。
3. 1回の印象で結論を出す。 「Bのほうが読みやすい気がした」は、その1本の印象です。5回の幅で見ます。
4. 読みやすさを、コメントの量だけで判断する。 読み手が知りたいのは、変えたい場所がどこにあるかです。量より、場所の見つけやすさで判断します。
5. よい出力だけを残す。 動かない出力や、極端に短い出力も、条件の一部です。捨てずに記録します。
6. 結果を別の環境に広げすぎる。 使うAIのモデルや設定が変われば、結果も変わりえます。記録にはモデルの名前と実施した日付を書いておきます。

次の行動

まず、依頼するゲームを1本決め、条件AとBの依頼文を保存してください。次に、交互に5回ずつ生成して符号を付け、計測ページに貼って記録表を埋めます。最後に、3つの質問で目的の箇所を探す時間を測れば、「一言の効果」が表面か設計かを自分のデータで判断できます。

結果が出たら、読みやすさを整えたコードを作品として公開するところまで進めてみてください。アソバースでは、HTMLまたはZIPをアップロードして、入力、表示の確認、公開の順に進められます。