コードが自分を説明できる世界——「セルフドキュメンティングコード」の限界と未来
2026.06.18執筆者：DigKnow株式会社 CTO 桑原 脩
「良いコードにコメントはいらない。コードそのものが仕様書だ」——シニアエンジニアなら、一度はこの言葉に頷いたことがあるはずです。命名を丁寧にし、関数を適切に分け、構造で意図を語らせる。確かにそれは美しい理想で、私自身いまも基本的には支持しています。ただ、この「コードが自分を説明する」という考え方が、どこまでを説明できて、どこから先は説明できないのか。その境界線が、AIがコードを書く時代になって、急にくっきり見えてきた気がしています。
セルフドキュメンティングコードは、確かに正しい
最初に立場を明確にしておきます。私はセルフドキュメンティングコードという思想を、否定する気は一切ありません。むしろ、長く支持してきた側です。Robert C. Martin の『Clean Code』をはじめ、多くの古典がこの理念を支えてきましたし、その正しさは今でも揺らいでいないと思っています。
この思想が解決した問題は本物でした。コメントは腐ります。実装を直してもコメントは直されず、半年後には「コードと矛盾するコメント」という、ないよりたちの悪いものが残ります。だったら、説明をコメントという別レイヤーに逃がさず、命名・関数分割・型・構造といったコードそのものに語らせよう——この発想は理にかなっています。`getData()` ではなく `fetchActiveSubscribers()` と書く。フラグの羅列ではなく、意図の伝わる列挙型にする。読み手が処理を追うだけで「何をしているか」がわかるなら、確かに別の説明書はいりません。
ここには、ひとつの暗黙の約束があります。書き手が、意図を込めながらコードを書いているという約束です。命名のひとつ、分割のひとつに判断が宿っているからこそ、コードは「自分を説明する」媒体になり得た。セルフドキュメンティングコードは、職人が一行ずつ意図を彫り込む前提のうえに成り立っていた思想なのです。
それでも、コードは「なぜ」を語れない
ただ、どれだけ丁寧に書いても、コードが構造上どうしても語れない領域があります。
セルフドキュメンティングコードが説明できるのは、「このコードが何をするか（what）」「どう動くか（how）」までです。優れた命名と構造は、処理の意図をかなりの精度で伝えます。けれど、「なぜ数ある選択肢のなかでこの設計を選んだのか（why）」「なぜここでは、あえて重複を許容したのか」「なぜこのライブラリを退け、こちらを採ったのか」——こうした意思決定の経緯は、どんなに可読性の高いコードにも書き込めません。採用された選択肢は残りますが、検討の末に捨てられた選択肢は、コードのどこにも残らないからです。
具体的な場面で考えてみます。あるエンジニアが、特定の条件のときだけ通常のキャッシュ処理を迂回する分岐を入れたとします。命名は明快で、処理の流れも追えます。けれど、レビューする側には「なぜこの迂回が必要なのか」が見えません。実は半年前、特定の大口顧客で起きた障害を回避するための判断だった——という背景は、コードのどこにも書かれていない。きれいに書けば書くほど、分岐は「当たり前にそこにあるもの」に見えてしまい、消していいのか残すべきなのかを、後任は判断できなくなります。
セルフドキュメンティングコードは、その「読めば伝わる」を書き手側から最大化しようとする試みです。けれど、最大化しても天井は天井としてある。コードが語れるのは「what」と「how」までで、「why」は構造上、別の場所にしか宿れないのです。
AIが書いたコードは「自分を説明」できるのか
ここに、AIコーディングがもう一段の揺さぶりをかけてきます。
セルフドキュメンティングコードは、書き手が意図を込める前提に立っていました。では、AIが生成したコードの命名や構造に、人間の意図はどれだけ宿っているでしょうか。
私自身、Claude Codeで生成したコードを読み返していて、奇妙な感覚に襲われることがあります。命名は驚くほど整っています。関数の粒度も適切で、見た目には「お手本のようなセルフドキュメンティングコード」です。けれど、その整った命名は、私が意図を込めて選んだものというより、AIが大量のコードから学習した「それらしい命名の最頻値」であることが少なくありません。表面はセルフドキュメンティングでも、その下に込められているはずの判断の密度が、薄い。読みやすいのに、なぜそう書いたのかを書いた本人が説明できない——この奇妙なねじれが、現場で静かに増えています。
加えて、AIが出すコードは「動作としては正しいが、このコードベース固有の語彙からはやや外れている」ことが珍しくありません。チームで長年使ってきた命名のクセも、ドメイン固有の用語も、与えなければAIは知りません。結果として、生成されたコードは「正しいが、このチームの方言ではない英語」のように、読めるのに馴染まない、という状態になります。文法的には完璧なのに、なぜか自分たちの言葉に聞こえない。
つまりAIは、セルフドキュメンティングコードの「見た目」を、いとも簡単に再現します。けれど、その思想が本当に依拠していた「意図の彫り込み」のほうは、必ずしも伴いません。きれいに見えるコードが、実は何も説明していない。可読性という表面が、理解という中身を保証しなくなりつつある、というのが私の見立てです。
限界の先にある未来——コードの「外」に意図を置く
では、セルフドキュメンティングコードという思想は、もう古いのでしょうか。私はそうは思いません。捨てるのではなく、役割を正しく限定すればいい、と考えています。
整理すると、向き合うべきは次の三点です。
①命名と構造でコードに語らせる努力は、これからも続ける価値がある。コードが語れる範囲を広げることに損はありません。
②ただし、コードが語れるのは「what」と「how」までだと割り切る。可読性を上げれば「why」まで残せる、という幻想は手放す。
③そして、コードには載らない「why」を、どこに、いつ、どう残すかを、開発フローの設計問題として正面から扱う。
重要なのは、これを個人の心がけや「ちゃんと書こう」という精神論に落とさないことです。意図は、書こうと思った瞬間に書けるものではなく、判断した瞬間に最も濃く、時間とともに揮発します。だとすれば、判断のすぐそばで意図が自然に残る仕組みを、フローのなかに埋め込むしかありません。コードの外に意図の置き場所を用意し、そこへ書く動機とタイミングを設計する——セルフドキュメンティングコードの限界の先にあるのは、たぶんこの話です。
AIがコード生成だけでなく、この「why」の記録そのものをどこまで肩代わりできるのか。その可能性と現実的な限界については、今後の記事で改めて掘り下げていく予定です。
まとめ
セルフドキュメンティングコードは、いまも正しい思想です。命名と構造でコードに語らせる努力には、確かな価値があります。ただし、コードが語れるのは「what」「how」までで、「why」は構造上、コードの外にしか宿れません。AIが書くコードは、その見た目を簡単に再現する一方で、意図の密度を伴わず、チームの語彙からもズレがちです。可読性が理解を保証しなくなりつつあるいま、コードに語らせる範囲を見極め、語れない「why」をどこに置くかを設計し直すこと。これが、この思想の限界の先で私たちが向き合うべき問いだと、私は思っています。