こんにちは！フロントエンド・アーキテクチャの現場を長年渡り歩いてきた者です。
JavaScriptって本当に自由で素晴らしい言語ですよね。変数を作るときに「これは文字です」「これは数字です」なんて堅苦しい宣言をしなくても、サクッと動いてくれます。おもちゃ箱をひっくり返したような自由さが、JavaScriptの最大の魅力です。
……ただ、現場が大きくなって、コードが何千行にもなってくると、その「自由さ」が牙を剥くんです。
- 「あれ？ この関数の引数、渡すのは文字列だっけ？ 数字だっけ？」
- 「チームメンバーが作ったこのオブジェクト、中にどんなプロパティが入っているのか分からないから、わざわざコードの海を潜って探しにいかなきゃ……」
そんな経験、ありませんか？
「TypeScriptを導入できれば一番いいんだろうけど、今のプロジェクトはプレーンなJavaScriptだし、ビルド環境を変える余裕もないよ！」という現場の悲鳴が聞こえてきそうです。
大丈夫ですよ。そんなあなたをそっと救ってくれる、めちゃくちゃ強力で、かつ手軽な秘密兵器があるんです。それが今回お話しする「JSDoc（ジェイズドック）」です。
—
JSDocってなぁに？ 身近な例えでお話ししますね
いきなり難しい専門用語を並べるのは野暮というものです。JSDocをイメージしてもらうために、こんな例えをさせてください。
あなたは今、街の小さなおしゃれな雑貨屋さんを営んでいます。お店にはたくさんの「引き出し付きの箱」がありますよね。
引き出しの外側に「中身のラベル（付箋）」が貼っていなければ、中身を確認するために一つひとつ引き出しを開けなくてはなりません。これは大変です。
JSDocは、まさにその「引き出しに貼るラベル」なんです。
JavaScriptのコード（引き出し）自体はそのままの自由な形でありながら、その上に「これはこういう箱で、中にはこういう名前のアイテムが入っていますよ」という説明書き（ラベル）をペタッと貼る。
そうすると、VS Codeなどのエディタがそのラベルを読んで、「あ、この引き出しを開けたらハンカチが入ってるんだな」と先回りして教えてくれるようになるんです。
これが、JSDocを用いた静支援（エディタによるサポート）の正体です。プログラムの挙動を変えるわけではなく、「開発している私たちのための設計図」をコードのなかにこっそり仕込むイメージですね。
—
まずは基本の「おじぎ」から：`@type` タグ
それでは、実際にエディタに貼る「ラベル」の書き方を見ていきましょう。まずは一番シンプルな `@type` タグです。
例えば、ユーザーの年齢を管理する変数があったとします。
/ @type {number} /
let userAge = 28;
おっと、「なんだこのコメントの親玉みたいなものは！」と驚かないでくださいね。
通常のコメントは `//` や `/ … /` ですが、JSDocのラベルとしてエディタに認識してもらうためには、先頭を `/` （アスタリスクが2つ） で始めるのがお約束のお呪い（おまじない）です。
この書き方をしておくと、もしうっかり別の場所でこんなことをしようものなら……
// エディタが「ちょっと待って！」と優しく教えてくれます
userAge = “二十八歳”; // 怒られはしないけど、波線で警告が出る！
エディタ（VS Codeなど）が、「おいおい、君はさっき『ここは数字（number）の箱だ』ってラベルを貼ったはずだぜ？」と、親切に波線で教えてくれるようになります。未然にバグを防げちゃうわけですね。
—
複雑なデータはお任せ！ `@typedef` と `@property` タグ
実際のWeb制作やアプリ開発では、単なる数字や文字列だけでなく、名前や年齢、住所などがひとまとめになった「オブジェクト」を扱うことが多いですよね。
例えば、お買い物の会員情報を表すオブジェクトを考えてみましょう。
/
- 会員情報を表すデータ型
- @typedef {Object} Member
- @property {string} name – 会員のお名前
- @property {number} age – 会員のご年齢
- @property {boolean} [isPremium] – プレミアム会員かどうか（なくてもOK）
/
ちょっと見慣れないタグが出てきましたね。ひとつずつほどいていきましょう。
1. `@typedef {Object} Member`
「これから『Member』という名前の新しいカスタムデータ型（設計図）を定義します宣言」です。
2. `@property {string} name`
「その設計図の中には、`name` という文字列（string）のプロパティがありますよ」という意味です。
3. `@property {boolean} [isPremium]`
おや、`isPremium` のまわりに `[]` （角括弧）がついていますね。これは「このプロパティは、あってもなくてもどっちでもいいですよ（オプショナルですよ）」という、現場でめちゃくちゃよく使う優しい気遣いタグです。
そして、この定義した設計図を、実際の変数に適用してみます。
/ @type {Member} /
const tanaka = {
name: “田中 太郎”,
age: 32,
isPremium: true
};
これで何が嬉しいかと言うと、あなたがコードを書いている途中に `tanaka.` と打った瞬間、VS Codeの補完機能が「ねえ、`name` と `age` と `isPremium` があるよ！」とピタッとリストを表示してくれるんです。
もう、プロパティ名をド忘れして「あれ、スペルミスしたっけ？」と悩む夜とはお別れです。
—
実務で役立つ！ ちょっとした極意とつまずきポイント
ここで、現場のチーフアーキテクトとして、初心者のあなたが引っかかりやすいポイントをこっそりシェアしておきますね。
Q. コメントが長くなってコードが見づらくなりそう……
A. 大丈夫、隠せます！
VS Codeなどのモダンなエディタは、JSDocの塊の左側に小さなくねくねした矢印（折りたたみアイコン）を出してくれます。邪魔なときはパタンと閉じちゃいましょう。実用性と美しさを両立できるのがJSDocのいいところです。
Q. 型の種類ってどんなものがあるの？
A. よく使う基本セットはこれだけ覚えておけばOKです！
- `string` （文字：「こんにちは」など）
- `number` （数字：`123` や `3.14` など）
- `boolean` （真偽値：`true` または `false`）
- `Array` （配列：`[1, 2, 3]` など。さらに `Array
` のように書くと「文字列の配列」にできます） - `function` （関数）
—
まとめ：今日からあなたのコードは、もっと優しくなる
JSDocを用いた型定義、いかがでしたでしょうか？
「TypeScriptを導入するぞ！」となると、ビルドツールの設定を変えたり、拡張子を `.ts` に変えたりと、最初のハードルがなかなかに高いものです。でも、JSDocなら今動いているその `.js` ファイルに、そのままコメントを書き足すだけで始められます。
未来の自分や、一緒に働くチームの仲間への「優しさの置き手紙」だと思って、ぜひ今日のコードから `@type` を1行、取り入れてみてください。
あなたのJavaScriptライフが、もっと快適で楽しいものになりますように。
それでは、また別の現場でお会いしましょう！
コメント