関数の説明コメントと実際の動きが食い違っていることに気づき、画面を見つめながら静かに考え込んでいる開発者

AIコーディング作成2026-09-28 "01:01"約17分

AIにdocstring・コメントを書かせる｜後で嘘にならない書き方

「この関数、None を渡すと空のリストが返るって書いてあったんですけど……例外で落ちました」

レビューでそう言われて、該当の関数を開いてみる。docstringには確かに「None の場合は空のリストを返す」と書いてあります。でもコードを読むと、その分岐は半年前の修正でなくなっていました。コードは直された。コメントは、そのまま残った。

しかもそのdocstring、書いたのは自分ではなく、AIに「この関数にdocstringを付けて」と頼んで出てきたものでした。引数も戻り値も例外も、きれいにそろっていて、読んだときは「助かる」と思ったはずです。

コメントが古くなるのは、昔からよくある話です。ただAIに書かせるようになってから、少し事情が変わりました。量が一気に増えること、そして整っているぶん、ずれていても疑われにくいことです。

この記事では、AIにdocstring・コメントを書かせるときに、あとで嘘にならない形にしておく方法を整理します。docstringとは、関数やクラスの先頭に書く「何をするものか」の説明文のこと。Pythonでは文字列として、JavaScriptやJavaではJSDoc・Javadocのようなコメントの形で書きます。

結論：順番は3つです。①絞る——コードを読めば分かることは書かせない。「なぜこうしたか」「呼ぶ側が知っておくべき約束」だけを残す。②確かめる——AIが書いたdocstringの引数・戻り値・例外・例を、1行ずつコードと突き合わせる。例はできれば実行して確かめる。③一緒に直す——コードを変えたら、同じ差分でコメントも直す。コメントもレビューの対象にする。

覚え方は 絞る → 確かめる → 一緒に直す。①で量を減らすと②が回り、②で一度正しくすると③で保ちやすくなります。

今日ぜんぶやる必要はありません。①の「なぜ、だけ残す」を1つの関数で試すだけでも、コメントの読み方が変わります。

何が起きているのか——AIのコメントは「今のコード」の写しになりやすい

大量の付箋から数枚だけを選び取る場面、書類と機械を見比べて確かめる場面、部品の交換と同時に説明書きの札も付け替える場面を並べた図 — 後で嘘にならないコメントの作り方。絞る→確かめる→一緒に直す。書く量を減らし、中身をコードと突き合わせ、コードを変えたら同じ手でコメントも直す

打ち手の前に、なぜAIに書かせたコメントがずれやすいのかを整理します。原因が見えると、どこを絞ればいいかが分かります。

1つ目は、AIは「コードに書いてあること」を言い換えるのが得意なこと。関数を渡して「docstringを付けて」と頼むと、AIはコードを読んで、その動きを日本語や英語に直します。# ユーザーIDでユーザーを取得する のような、コードと同じことを2回書いたコメントがたくさんできます。コードと同じことを書いているぶん、コードが変わった瞬間にずれます。

2つ目は、「なぜ」はコードの外にあること。「この外部APIは100件ずつしか返さないので分割している」「経理の締めに合わせて、ここは日本時間で切っている」。こうした理由は、打ち合わせや過去の障害の中にあって、コードだけを渡されたAIには見えません。いちばん残したいコメントほど、AIには書けないのです。

3つ目は、もっともらしく埋めてしまうこと。「例外」の欄があれば、何か書こうとします。実際には投げない例外や、呼び出し先の実装に依存する挙動を、それらしく書いてしまうことがあります（AIのハルシネーションの見抜き方｜開発現場で気づく型）。

4つ目は、量が増えると読まれなくなること。全関数にAIがdocstringを付けると、ファイルの半分がコメントになることもあります。全部に書いてあると、どれが大事な注意書きか分からなくなり、結局だれも読まなくなります。

5つ目は、コメントはテストで落ちないこと。コードが間違っていればテストが落ちますが、コメントが間違っていても何も起きません。ずれは、誰かが信じて使った日にはじめて表に出ます。

裏を返すと、これは書き手の不注意の話ではなく、書かせ方と直し方の仕組みの話です。書く量を絞り、中身を確かめ、直す流れに組み込めば、AIはコメント作りのかなり頼れる相棒になります。

具体例——つい、こうなりがちという形

どれも「ないよりはあったほうがいい」という善意から生まれます。心当たりのある行があれば、そこだけ見れば十分です。

コードをそのまま言い換えたコメント：i += 1 # iを1増やす。読む人の助けにならず、コードが変わると真っ先にずれます。
消えた分岐の説明が残っている：冒頭の例のように、「None なら空を返す」「0件なら例外」など、修正で消えた挙動が docstring にだけ残る。
引数の説明が、引数の並びと合っていない：引数を1つ足した、名前を変えた、順番を入れ替えた。docstringの Args: だけが古い並びのまま、ということがよくあります。
書かれている例が、実行すると動かない：docstringの使用例が、古い呼び出し方や、存在しないオプションを使っている。例はいちばんコピーされる場所なので、影響が大きくなります。
「高速」「安全」「スレッドセーフ」と書いてある：根拠のない性質をAIが添えてしまう。読んだ人はそれを前提に使います。
TODOやFIXMEが、誰のものか分からない：AIが「TODO: エラー処理を追加」と書き、そのまま何年も残る。
生成したファイルの先頭に、長い説明が付いている：モジュールの目的、使い方、注意点が何十行も並び、中身と合っているか誰も確かめていない。
仕様書に書くべきことが、コメントに書いてある：業務のルールがコメントにだけあり、仕様書や設計書と食い違っている（仕様書・設計書のドラフトをAIで作る｜叩き台の作り方と注意点）。

影響——ずれたコメントは、ないコメントより迷わせる

急いで全部消さないと危ない、という話ではありません。ただ、ずれたときの迷い方が大きい種類の問題なので、書いておきます。

読む人がコードより先にコメントを信じる：とくに他の人の関数を呼ぶときは、docstringだけ読んで使うことが多いものです。ずれていれば、そのまま誤った使い方が広がります。
AIにも誤った前提が伝わる：いまはコードを読ませてAIに相談することが増えています。古いコメントは、次にAIが書くコードの前提にもなってしまいます（既存コードにAIを馴染ませる文脈の渡し方｜実務の型）。
調査の遠回りになる：障害のときにコメントを手がかりに追いかけ、実際のコードと違うと分かるまでに時間がかかります。
コメント全体が信用されなくなる：何度かずれに当たると、「ここのコメントは当てにならない」と思われます。本当に大事な注意書きまで読まれなくなるのが、いちばん惜しいところです。

少し安心できる話をすると、この領域は、書く量を減らすほど楽になります。全部を正しく保とうとしなくていい。残すものを絞れば、確かめる量も直す量も一緒に減ります。

明日からやること（絞る・確かめる・一緒に直す）

上から順に、小さく始められます。今日は①だけで構いません。

1. 絞る——「なぜ」と「約束」だけを書かせる

AIに「docstringを付けて」とだけ頼むと、コードの言い換えが返ってきます。何を書いてほしいかを先に伝えるだけで、出てくるものがかなり変わります。

コメントに残すものを決めておく。目安は次の3つです。（1）なぜこう書いたか（外部の制約、過去の障害、業務のルール）、（2）呼ぶ側が知っておくべき約束（引数の前提、戻り値の意味、投げる例外、副作用）、（3）わざとそうしている箇所（一見まちがいに見えるが意図がある書き方）。
コードを読めば分かることは書かない。「ユーザーを取得する」「ループで合計する」は、関数名と中身で伝わります。伝わらないなら、コメントを足すより名前を直すほうが先です（「動くけど読めない」AI生成コードを保守可能にする手直し手順）。
「なぜ」はAIに渡す。AIに書けないのは理由です。打ち合わせのメモ、チケット、障害の記録を一緒に渡すと、AIは理由をコメントの形に整えるのを手伝ってくれます。渡していない理由を推測で書かせないのがコツです。
docstringを付ける範囲を絞る。まずは他の人やチームから呼ばれる関数・公開しているAPIから。中だけで使う小さな関数は、名前が分かりやすければ無理に付けなくて大丈夫です。
書き方の形式はチームでそろえる。PythonならGoogle形式やNumPy形式、JavaScript・TypeScriptならJSDoc、JavaならJavadocのように、すでに使っている形式を先に伝えると、AIが混ぜずに書いてくれます（AIにコーディング規約を守らせる｜指示とチェックの仕込み方）。

2. 確かめる——書かれたことを、1行ずつコードと突き合わせる

AIが書いたdocstringは、コードの説明ではなく、コードについての主張として読みます。主張なので、確かめます。

引数：docstringに並んでいる引数と、関数の実際の引数を並べて見比べる。名前・順番・省略したときの値が合っているか。
戻り値：「空のリストを返す」「None を返す」「見つからなければ例外」。それぞれの分岐がコードに本当にあるかを探します。「この場合はこう返す」と書いてあるのに、その分岐がコードに見当たらなければ、ずれのサインです。
例外：書かれている例外を、コードの中で本当に投げているか。呼び出し先から上がってくる例外まで書くなら、呼び出し先を実際に読んだうえで書く。
例：docstringに使用例があるなら、実際に動かしてみる。Pythonには、docstringの中の例をそのままテストとして実行できる doctest という標準の仕組みがあります。ほかの言語でも、例をテストコードに写しておけば、ずれたときに気づけます。
性質を表す言葉：「高速」「安全」「スレッドセーフ」「冪等」のような言葉は、根拠を説明できるものだけ残す。説明できなければ消して大丈夫です。
ここは、AIに逆向きに確かめさせる手もあります。書かせたdocstringとコードを並べて渡し、「docstringの記述のうち、コードから裏付けられないものを挙げて」と頼むと、ずれの候補を拾ってくれます。最後に判断するのは自分ですが、見る場所が絞れます。

3. 一緒に直す——コードの差分に、コメントの差分を含める

コメントがずれるのは、コードを直したときに、コメントを直す流れがないからです。直す流れに、コメントを最初から入れておきます。

コードを変えたら、同じ差分でコメントも見る。関数の引数・戻り値・分岐を変えたら、そのdocstringも同じコミットで直します。あとでまとめて直す、はたいてい来ません。
AIに修正を頼むときは、コメントの更新も頼む。「この修正に合わせて、影響するdocstringとコメントも直して。直す必要がないものは直さないで」と一言添えます。直したコメントも差分に出るので、レビューで見られます（AIリファクタリングの差分レビュー｜壊さず確認する手順）。
レビューの観点にコメントを入れる。「振る舞いが変わった関数のdocstringは更新されているか」を、チームのレビュー項目に1行足しておきます（AI生成コードのレビュー・検証チェックリスト｜使う前に見る所）。
合わないコメントは、直すか消す。どう直せばいいか分からないコメントは、消すほうが安全なこともあります。間違った説明より、説明がないほうが、読む人はコードを確かめに行きます。
TODOには、持ち主と理由を付ける。「TODO(担当者名): 100件を超えたときの分割。チケット番号」のように。AIが付けた持ち主のないTODOは、見つけたときに片づけるか、チケットに移します。
引数や型の説明は、できるだけコードに寄せる。型ヒントや型定義で表せることは、コメントより型で書くほうがコンパイラや静的解析が確かめてくれます。コメントに残すのは、型では表せない約束だけにできると楽になります。

AIに相談するときのプロンプト（コピーして使えます）

何も伝えないと、AIはコードの言い換えを全部の関数に付けてきます。書くもの・書かないもの・推測しないことを、先に伝えるのがコツです。

次の関数に、後で嘘にならないdocstringとコメントを付ける手伝いをお願いします。

①docstringは、呼ぶ側が知っておくべき約束だけを書いてください（引数の前提、戻り値の意味、投げる例外、副作用）。形式は（　）でそろえてください。
②コードを読めば分かることは書かないでください。処理の手順をなぞるだけのコメントは不要です。
③「なぜこう書いたか」のコメントは、下に渡した背景の情報から分かるものだけ書いてください。背景が渡されていない箇所は推測で理由を書かず、「理由の確認が必要」と一覧にしてください。
④例外や戻り値は、このコードの中で実際に確かめられるものだけを書いてください。呼び出し先の挙動に依存するものは、その旨を書き分けてください。
⑤「高速」「安全」などの性質を表す言葉は、根拠をコードから示せる場合だけ使ってください。
⑥最後に、docstringに書いた内容のうち、コードから裏付けを確かめてほしい箇所を一覧にしてください。

対象のコード：（　）　背景の情報（チケット・打ち合わせメモ・過去の障害など）：（　）　使っているdocstringの形式：（　）

③の一文が効きます。「分からない理由は書かずに一覧にして」と先に伝えるだけで、それらしい理由が作られてしまうのを防げます。一覧に出てきた箇所は、知っている人に聞きにいく入口になります。

出てきたdocstringは、次の3点だけ自分の目で確かめます。（1）自分が渡していない背景が、理由として書かれていないか、（2）書かれている例外・戻り値の分岐が、コードに本当にあるか、（3）使用例がそのまま動くか。この3点は、文面が整っていてもずれていることがあります（AIが書いた単体テストを信用しすぎない｜確認ポイント）。

後で嘘にならないコメントのチェックリスト（コピーして使えます）

全部に○が要るわけではありません。気になった行だけで十分です。

① 絞る

コードを読めば分かることを、コメントに書いていないか
「なぜこう書いたか」の理由を、背景の情報つきでAIに渡したか
渡していない理由を、AIに推測で書かせていないか
docstringを付ける範囲を、外から呼ばれる関数・公開APIから始めたか
docstringの形式を、チームで使っているものにそろえたか

② 確かめる

引数の名前・順番・省略時の値が、docstringと一致しているか
戻り値の分岐が、コードに本当にあるか
書かれている例外を、コードの中で本当に投げているか
使用例を実際に動かしたか（doctest やテストへの写しなど）
「高速」「安全」などの言葉に、説明できる根拠があるか

③ 一緒に直す

コードの変更と同じ差分で、影響するコメントも直したか
AIに修正を頼むとき、コメントの更新もあわせて頼んだか
レビューの観点に「振る舞いが変わった関数のdocstring」を入れたか
合わないコメントを、直すか消すかしたか
TODOに持ち主と理由を付けたか

この記事のまとめ

AIに書かせたコメントがずれるのは、書き手の不注意ではなく、書かせ方と直し方の仕組みの問題です。AIはコードを言い換えるのが得意なぶん、コードと同じことを書いたコメントが増え、コードが変わった瞬間にずれていきます。

やることは3つ。①絞る——コードを読めば分かることは書かせず、「なぜ」と「呼ぶ側への約束」だけを残す。②確かめる——引数・戻り値・例外・例を、1行ずつコードと突き合わせ、例は動かしてみる。③一緒に直す——コードを変えたら同じ差分でコメントも直し、コメントもレビューの対象にする。

AIに頼むときは、「分からない理由は推測で書かずに一覧にして」と先に一言添える。それだけで、コメントが「それらしい文章」から「確かめられる約束」に変わります。