そのコメント、誰が検証していますか

/** * <b>そのコメント、誰が検証していますか</b> * * Ruby / PHP / Java / Deno / Rust のドキュメントコメントは * 何を検証できて、何ができないのか。 * そして、いま書くべきことは何か。 * * @author こうの * @see */ "大Funabashi.dev"

# <b>例えば、こう書いたとする</b> # # Ruby のドキュメントコメントは # で書く。 # 型は @param / @return にタグとして書ける。 # ユーザーを取得する。 # 見つからない場合は RecordNotFound を投げる。 # # @param [String] user_id ユーザーID # @return [User] 見つかったユーザー def find_user(user_id) nil end 2

# <b>YARD にかけてみる</b> # # YARD は Ruby のドキュメント生成ツール。 # 「例外を投げる」と書いて nil を返しているが、さて。 $ yard doc Methods: 1 (0 undocumented) 100.00% documented 警告ゼロ。ドキュメント化率は満点 3

/** * <b>今日の軸</b> * * <ol> * <li>検証できるか —— 嘘を検出できるか * <li>距離 —— 同じ情報が、何箇所に書かれているか * </ol> * * @see "Ruby はいま見ました。あと4言語" */ 4

/**
* <b>PHP：こう書いたとする</b>
*
* PHPDoc は Javadoc に近い記法で、太字は HTML タグ。
* 型は書けるが、PHP 本体はこれを読まない。
*/

/**
* @return array<int, User>
*/
function getUsers(): array {
return ['a' => 'not a user'];
}

「 User の配列を返す」と書いてある。この型は PHP の言語仕様にはなく、コメントにしか書けない
5

/** * <b>PHP：かけてみる</b> * * 同じファイルを、2つのツールにかける。 */ $ php -l users.php No syntax errors detected # PHP 本体の構文チェック $ phpstan analyse users.php # 静的解析ツール should return array<int, User> but returns array<string, string> PHP 本体はコメントを無視する。PHPStan はコメントを型として読む 6

/**
* <b>Java：こう書いたとする</b>
*
* Javadoc は HTML を書ける記法なので、太字はタグ。
* コード例は {@code @snippet} で別ファイルを参照する。
*/
snippet-files/CalcSnippets.java（実在するコード）

// @start region="basic"
int result = Calc.add(1, 2);
// @end
Calc.java（ドキュメント側）

/**
* {@snippet class="CalcSnippets" region="basic"}
*/

ドキュメントに書くのは「どのファイルのどの範囲か」だけ

7

/** * <b>Java：javadoc は HTML を生成する</b> * * コマンドを実行すると、このコメントが HTML になる。 */ {@snippet} の参照先が、そのまま展開されている 8

/**
* <b>Java：参照先を壊してみる</b>
*
* 参照する region の名前を、わざと間違える。
*/
Calc.java — region 名を typo させる

{@snippet class="CalcSnippets" region="typo"}
$ javadoc -Xdoclint:none ...
error: region not found: "typo"

9

/** * **Deno：こう書いたとする** * * JSDoc のコメント。中身は Markdown なので、 * 太字はアスタリスク2つ。 */ mod.ts /** * ```ts * assertEquals(add(1, 2), 999); * ``` */ export function add(a: number, b: number): number { return a + b; } コメントに書いた「使用例」。ただし 1 + 2 は 999 ではない 10

/** * **Deno：テストを走らせる** * * Deno は JavaScript / TypeScript のランタイム。 */ Deno — JavaScript / TypeScript のランタイム $ deno test --doc # --doc: ドキュメント内のコード例もテストする error: AssertionError: Values are not equal. 3 + 999 型が違えば TS2322 。型チェックも実行も両方される 11

//! **Rust：こう書いたとする** //! //! rustdoc のコメントは /// と //! で書く。 //! 中身は Markdown。 README.md # demo ```rust assert_eq!(add(1, 2), 999); ``` src/lib.rs — これ1行だけ #![doc = include_str!("../README.md")] README の中身を、そのままこのライブラリのドキュメントにする 12

//! **Rust：テストを走らせる** //! //! README に書いた例が、テストとして実行される。 $ cargo test test src/lib.rs - (line 5) ... FAILED assertion `left == right` failed left: 3 right: 999 README に書いた例が doctest として実行されている 13

//! **実在のライブラリでも** //! //! clap は Rust の定番コマンドライン引数パーサ。 clap/src/lib.rs:411 #![doc = include_str!("../examples/demo.rs")] 動くサンプルプログラムが そのままドキュメント toml / image は README を、axum は章ごとの Markdown を埋め込んでいる 14

同じ情報が2箇所にあると 必ずズレる 15

/** * <b>答えは3つしかない</b> */ 距離をゼロにする Rust include_str! / Java {@snippet} ズレを検出する doctest（Deno / Rust）/ PHPStan / doclint 諦める YARD の型タグ 16

# <b>では、こう書いた場合は？</b> # ユーザーを取得する def get_user 情報量ゼロ 名前から100%予測できる＝読んでも何も新しく分からない 17

ドキュメントの価値 ＝ コードから予測できない度合い 18

/** * <b>読者が変わった</b> * * <p><b>昔</b> —— 未来の誰か。非同期・不特定。だから網羅的に、丁寧に。 * <p><b>今</b> —— 今のAIと、今の自分。同期的・具体的。 */ 19

AI時代に一番効くのは 実行されるドキュメント 嘘をつかないから 20

/** * <b>コードから予測できないことだけ書けばいい</b> * * <p>そして、書いたなら検証する。 * * @author こうの * @see "大Funabashi.dev" */ 21