ない関数の説明
アシスタントに README を頼むと、数秒で、読みやすい文書が返ります。ところが、その中に、コードにない関数の説明が入っていることがあります。
文書は、読む人が最初に信じるものです。間違いがあれば、使う人を迷わせます。文書をコードと突き合わせる方法を学びます。
このレッスンのゴール
メモ
アシスタントが書いた文書を、コードと突き合わせて、コードが守らない主張を見つけられる。
キーワード
| ことば | いみ |
|---|---|
| 文書 | コードの使い方を、人に伝える文章 |
| 主張 | 文書が、コードについて言い切っていること |
| 突き合わせ | 主張を、コードや実行結果と見比べること |
| なぜのコメント | コードがそう書かれた理由を説明するコメント |
| 古い文書 | コードが変わったのに、直されていない文書 |
学生が入力するセルは、このプレビューでは空白です。
コメントは「なぜ」を書く
アシスタントが書くコメントは、コードを日本語に直しただけのことがよくあります。「税を足す」と書かれても、コードを読めば分かります。
読む人が知りたいのは、なぜです。なぜ切り捨てるのか。なぜこの順なのか。理由を書くコメントだけが、コードにない情報を足します。
例: 2つのコメント
| コメント | 何を言っているか | 役に立つか |
|---|---|---|
| 税を足す | コードがすることを、言い直した | 足りない |
| 円未満は、決まりで切り捨てるので floor を使う | コードの理由を言った | 役に立つ |
学生が入力するセルは、このプレビューでは空白です。
ありうる頼み方
こんな頼み方があります。「cart.js の README を書いてください。cart.js にある関数だけを書いてください。それぞれ、引数と、返すものを書いてください」
アシスタントの返事は、毎回違います。返ってきた文書の、関数の名前と約束を、1つずつ cart.js と見比べます。
文書の名前は、コードにあるか
次の Run は、フォルダー demo-docs/ に、買い物かごのコードと、手で書いた README と、名前を確かめるスクリプトを書きます。README の関数の名前は、「」で囲んであります。
スクリプトは、README に出た名前が、コードにあるかを調べます。README はアシスタントの答えではなく、確かめる練習用です。
かごのコードを書く
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' '// 買い物かごの小さな部品。かごは、品物の配列。' 'function addItem(cart, name, yen) {' ' cart.push({ name: name, yen: yen });' ' return cart;' '}' 'function removeItem(cart, name) {' ' const index = cart.findIndex((item) => item.name === name);' ' if (index >= 0) cart.splice(index, 1);' ' return cart;' '}' 'function total(cart) {' ' let sum = 0;' ' for (const item of cart) sum = sum + item.yen;' ' return sum;' '}' 'module.exports = { addItem, removeItem, total };' > demo-docs/cart.js"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
確かめる README を書く
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' '# 買い物かごの部品' '「addItem(cart, name, yen)」は、品物を足したかごを返します。' '「removeItem(cart, name)」は、品物を除いた新しいかごを返し、元のかごは変えません。' '「total(cart)」は、合計の円を返します。' '「applyCoupon(cart, code)」は、クーポンを使った合計を返します。' > demo-docs/README.md"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
名前を調べるスクリプト
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' 'const fs = require(\"fs\");' 'const cart = require(\"./cart.js\");' 'const text = fs.readFileSync(\"README.md\", \"utf8\");' 'const found = text.match(/「[A-Za-z]+\(/g);' 'for (const raw of found) {' ' const name = raw.slice(1, raw.length - 1);' ' console.log(name + \": \" + (name in cart ? \"ある\" : \"ない\"));' '}' > demo-docs/names.js"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
名前を調べる
docker exec -w /home/node/project/demo-docs agent node names.jsここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
文書の約束を動かして確かめる
名前があるだけでは足りません。README は、removeItem について、元のかごは変えない、と言っています。この約束は、動かさないと分かりません。
次の Run は、2品入ったかごから1品を除き、返ったかごと元のかごの品数を表示します。約束が正しければ、元は2品のままです。
約束を確かめる書き込み
docker exec -w /home/node/project agent sh -c "mkdir -p demo-docs && printf '%s\n' 'const cart = require(\"./cart.js\");' '// 文書は、元のかごは変えない、と言っている。' 'const original = [{ name: \"茶\", yen: 150 }, { name: \"パン\", yen: 200 }];' 'const result = cart.removeItem(original, \"茶\");' 'console.log(\"返ったかごの品数: \" + result.length);' 'console.log(\"元のかごの品数: \" + original.length);' > demo-docs/claim.js"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
約束を動かして確かめる
docker exec -w /home/node/project/demo-docs agent node claim.jsここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
よくある間違い
注意
文書はコードを見て書かれたのだから、正しいと思う人が多いです。アシスタントは、あるはずの関数や、あってほしい動きを、もっともらしく書くことがあります。主張は、1つずつコードと見比べます。
さらに: 別のコードで試す
今は、この考えを別のコードで試すのに、よい時です。ラボのバグには触れません。代わりに、shop.js の写しの、関数の説明を頼みます。
返ってきた説明の、関数の名前を、コードと見比べます。約束が1つあれば、小さな入力で動かし、結果を書き出します。