最近、Claude CodeやGitHub Copilotを使っているとこんな声を聞くことがあります。
AIがコードを読めるならJavadocはいらないのでは？
私も一時期そう考えていました。
しかし実際にAIを開発へ活用するようになって感じたのは、Javadocの価値は下がっていないということです。
むしろ用途が変わり、これまで以上に重要になる場面が増えています。
はじめに
従来のJavadocは主にAPI利用者向けのドキュメントでした。
例えば以下のような用途です。
- APIの説明
- 引数の説明
- 戻り値の説明
- 使用例の記載
しかしAIがコードを書く時代になると、単なる引数説明の価値は相対的に下がります。
なぜならAIはメソッド名や型定義からある程度推測できるからです。
一方で、AIが苦手なのは次のような情報です。
- なぜその処理が必要なのか
- どの業務ルールを守るべきか
- どんな前提条件があるか
- 何を壊してはいけないか
つまり、
設計意図や業務ルールを伝えるためのJavadoc
が重要になってきています。
気付き
AIはコードを読めます。
しかし設計者の意図までは読めません。
例えば次のコードです。
public void approve(Order order) {
...
}
人間なら、
- 仮承認？
- 本承認？
- 誰でも承認可能？
- キャンセル済み注文は？
などを考えます。
しかしAIはそこまで推測できません。
結果として、
動くコードは作るが、業務的に誤ったコードを生成する
ことがあります。
そこで重要になるのがJavadocです。
Javadocは人間向けドキュメントから、
AIへ設計コンテキストを伝える媒体
へ進化しつつあります。
悪いJavadoc例
よく見かけるのがこちらです。
/**
* 注文を承認します。
*
* @param order 注文
*/
public void approve(Order order) {
}
これはほぼコードと同じ情報です。
AIにとっても人間にとっても価値は高くありません。
良いJavadoc例
設計意図や業務ルールを書くと価値が生まれます。
/**
* 注文を承認する。
*
* <p>契約条件:
* <ul>
* <li>注文状態が PENDING であること</li>
* <li>キャンセル済み注文は承認不可</li>
* </ul>
*
* <p>事後条件:
* <ul>
* <li>状態が APPROVED へ遷移する</li>
* <li>承認日時が設定される</li>
* </ul>
*
* <p>不変条件:
* <ul>
* <li>承認済み注文は再承認できない</li>
* </ul>
*/
public void approve(Order order) {
}
ここまで書かれていると、Claude CodeやCopilotはかなり高精度に意図を理解できます。
実質的にDesign by Contractの情報を与えている状態です。
Design by Contractとの関係
ここで登場するのが Design by Contract（契約による設計） です。
Design by Contractでは主に以下を定義します。
| 種類 | 内容 |
|---|---|
| Preconditions | 呼び出し前に満たすべき条件 |
| Postconditions | 処理後に保証される条件 |
| Invariants | 常に維持される条件 |
例えば注文承認処理であれば、
- Preconditions：注文状態がPENDINGである
- Postconditions：注文状態がAPPROVEDになる
- Invariants：承認済み注文は再承認できない
となります。
AIはコードから業務ルールを推測するのが苦手です。
しかし契約として明文化されていれば、それを前提にコード生成やレビューを行えるようになります。
Java 23のMarkdown Javadocが追い風
近年はJavadoc自体も進化しています。
Java 23ではMarkdown形式のJavadocが正式サポートされました。
例えば次のように記述できます。
/// 注文を承認する
///
/// ## Preconditions
///
/// - 状態が `PENDING`
/// - キャンセル済みではない
///
/// ## Postconditions
///
/// - 状態が `APPROVED`
/// - 承認日時が設定される
///
/// ## Invariants
///
/// - 承認済み注文は再承認不可
public void approve(Order order) {
}
これまでのようなHTMLタグ中心の記述よりも圧倒的に読みやすくなりました。
人間だけでなくAIにとっても理解しやすいフォーマットです。
Claude Codeとの相性が良い理由
Claude Codeを使っていると分かりますが、AIはコードだけでなく周辺情報も積極的に参照します。
特に以下の情報は生成結果へ大きく影響します。
- Javadoc
- README
- ADR
- 設計書
- テストコード
その中でもJavadocはソースコードの最も近くに存在します。
つまりAIにとっては、
設計者がコードに埋め込んだ最も信頼できるコンテキスト
になります。
実際にClaude Codeへ実装依頼を行う際も、
Javadocが充実しているコードベースとそうでないコードベースでは、生成品質に大きな差が出ます。
Spring Boot Serviceでの実践例
私が最近意識しているのは、Serviceクラスの公開メソッドに設計意図を書くことです。
@Service
public class RefundService {
/**
* 返金手段を変更する。
*
* <p>前提条件:
* <ul>
* <li>顧客が本人確認済みであること</li>
* <li>返金処理中でないこと</li>
* </ul>
*
* <p>業務ルール:
* <ul>
* <li>20万円以上は銀行口座返金を選択可能</li>
* <li>クレジットカード返金は金額制限なし</li>
* </ul>
*
* <p>不変条件:
* <ul>
* <li>顧客アカウントと返金口座は1対1である</li>
* </ul>
*/
public void changeRefundMethod(...) {
...
}
}
この情報はコードから推測できません。
しかしAIにとっては極めて重要なコンテキストになります。
またレビュー時にも、
- 契約違反
- 業務ルール違反
- 不変条件の破壊
を検出しやすくなります。
実践方法
私がおすすめするのは以下の優先順位です。
- 設計意図を書く
- 業務ルールを書く
- 不変条件を書く
- 事前条件を書く
- 事後条件を書く
逆に、
/**
* 顧客を取得する
*
* @param id 顧客ID
* @return 顧客
*/
のようなコードを読めば分かる説明は優先度を下げても問題ありません。
AI時代に価値が高いのは、
「何をしているか」ではなく「なぜそうするのか」
だからです。
まとめ
AI時代になったからJavadocが不要になるわけではありません。
むしろ役割が変わりました。
従来のJavadocはAPI利用者向けでした。
これからのJavadocは、
- 設計意図
- 業務ルール
- 不変条件
- Design by Contract
をAIへ伝えるための設計ドキュメントとして機能します。
Claude CodeやCopilotがコードを書く時代だからこそ、
「コードを説明するJavadoc」ではなく、「設計を説明するJavadoc」
を書く価値が高まっているのではないでしょうか。
本記事は、JJUG CCC 2026 Springで得た学びをもとに整理・考察した内容です。