ドキュメントを書かせる

ドキュメントは AI が得意な仕事

コードを読んで説明を書く作業は、AI がとても得意です。関数の並びを見て、何をする道具なのかをまとめ、使い方の例まで書けます。人間がいちばん後回しにしがちな仕事なので、任せる価値が大きい部類です。

ただし丸投げすると、当たり障りのない一般論が返ってきます。何を書いてほしいのかの型を渡すと質が変わります。

README に次の4つを書いてください。
  このプログラムが何をするものか
  使い方の例をコード付きで1つ
  各関数の引数と戻り値
  制限や注意点

ドキュメントを書かせると仕様の穴が出る

これが本当のねらいです。AI に説明を書かせると、説明できない部分が浮かび上がります。

この関数は日付ごとに合計します。
ただし日付の形式については、コードからは判断できませんでした。

こう返ってきたら、それは仕様が決まっていないということです。人間が読んでも分からないものは、AI にも分かりません。書けないと言われた箇所こそ、決めるべき仕様です。

docstring は最も近いドキュメント

別ファイルの README も大事ですが、コードのすぐ横に書く説明のほうが陳腐化しにくいです。Python なら docstring です。

def daily_total(records):
    """日付ごとに金額を合計して、日付順に並べた辞書を返す"""

この1行があると、次に読む人 (未来の自分と AI) が中身を読まずに用途を掴めます。AI に説明を書かせるときは、コードと説明を同時に触らせると、両者がずれません。

説明と実装がずれていたら

よくあるのは、docstring には「日付順に並べる」と書いてあるのに、実装は並べていないという食い違いです。このとき直すべきは、たいてい実装のほうです。書かれた説明は誰かが期待した仕様だからです。

悪い   説明のほうを実装に合わせて書き換えて
良い   説明が正しいものとして、実装を説明どおりに直して

どちらを正とするかは人間が決めます。AI に「どちらかに合わせて」と頼むと、楽なほう (説明の書き換え) を選びがちです。

今回の演習

日付ごとの合計を出す関数があります。docstring には日付の昇順で返すと書いてありますが、実装がそうなっていません。説明を正として、実装を直させてください。

• 触ってよいのは kakeibo.py だけです
• docstring のほうを書き換えて辻褄を合わせるのは禁止です
• daily_total 関数の戻り値で採点します