ドキュメントを書かせる

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

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

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

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

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

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

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

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

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

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

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

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

今回の演習

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

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