こんにちは！フロントエンドの現場を長年歩んできたチーフアーキテクトの私です。
JavaScriptって、書けばすぐに動くし、変数に数字を入れていたと思ったら急に文字を入れられたりして、本当に自由で優しい言語ですよね。……でも、その「優しさ」が、実務の現場では時として「魔界」への片道切符になるんです。
「あれ、この関数の引数には何を渡すんだっけ？」
「文字列だと思って処理したら、なんか `undefined` が返ってきたぞ……！」
こんな絶望、あなたも経験したことがありませんか？大規模なアプリになると、この「型（データがどんな種類のものか）」の把握ミスだけで、夜な夜なデバッグに追われることになります。
「でも、TypeScriptを導入するにはまだ早いし、ビルド環境も難しそう……」
そんなあなたにこそ知ってほしいのが、JavaScript標準の機能だけで静的解析（コードの間違いを事前に見つけること）をやってしまうJSDoc（`@param` と `@returns`）という秘密兵器です。
今回は、TypeScriptを導入しなくても、今日からあなたのエディタが優秀な相棒に生まれ変わる魔法のテクニックを、優しく紐解いていきましょう！
—
1. 関数は「自動販売機」だと思うと分かりやすい
まずは、関数（Function）というものをイメージしてみましょう。
JavaScriptの関数は、身の回りにある「自動販売機」によく似ています。
1. お金（引数：ひきすう）を入れる
2. 自動販売機の中で内部の処理が動き、
3. ジュース（戻り値：もどりち）が出てくる
これが関数の基本です。でも、もし自動販売機に「100円を入れるついでに、Suicaもタッチして、さらに鼻歌も歌え」なんて書いてあったらどうでしょう？ 買う側も、作る側も大パニックですよね。
「この穴には何を入れるべきで、何が出てくるのか」を、誰が見ても一目でわかるように看板を立ててあげること。それが、今回紹介する `@param` と `@returns` の役割なんです。
—
2. JSDocってなぁに？（怖くないよ、ただのコメントです）
JSDoc（ジェイズドック）と聞くと、なんだか難しそうな専門用語に聞こえるかもしれませんが、正体は「ちょっと特別な書き方をしたコメント」です。
JavaScriptのエンジンは、コメント（`/ … /` で囲まれた部分）を基本的には無視します。だから、ここに何を書いてもプログラムが壊れることはありません。
しかし、VS Codeなどの現代のエディタや、JavaScriptの解析ツール（CheckJS）は、この特別なコメントをこっそり読んでこう言ってくれます。
- 「おっ、この関数は数値を求めているのに、文字（文字列）が入れようとされてるよ！危ない危ない！」
- 「あれ？ 戻り値を使う予定なのに、この関数何も返してない（`undefined`）よ！」
TypeScriptという大工事をしなくても、エディタが勝手にあなたミスを水際で防いでくれるようになるんです。
—
3. 実践！お買い物の計算をしてみよう
百聞は一見に如かず。実際にコードを見てみましょう。
今回は、「商品の価格」と「消費税率」を渡して、合計金額を計算してくれるお利口さんな関数を作ってみます。
まずは、JSDocなしの「普通のJavaScript」から。
// 【Before】何も書いていない、自由だけどちょっぴり不安な関数
function calculateTotal(price, taxRate) {
return price (1 + taxRate);
}
// 使えるけれど、priceに “1000円”（文字）を入れてもエラーにならない……
let total = calculateTotal(“1000円”, 0.1);
このコード、動かしてみると `NaN`（Not a Number：数字じゃないよ！）という謎の文字になって返ってきて、頭を抱えることになります。
ここに、魔法の看板（JSDoc）を立ててみましょう！
/
- 商品の価格と消費税率から、税込の合計金額を計算するよ
- @param {number} price – 商品の本体価格（半角の数字を入れてね）
- @param {number} taxRate – 消費税率（例: 0.1 なら 10% だよ）
- @returns {number} 計算された税込の合計金額
/
function calculateTotal(price, taxRate) {
return price (1 + taxRate);
}
// さあ、ためしに使ってみよう！
const myTotal = calculateTotal(2000, 0.1);
console.log(myTotal); // 2200 がちゃんと出てくるよ！
ここで注目してほしいポイント！
関数の一番上に、`/` から始まるコメントを書きました。これがJSDocです。
- `@param {型} 名前 – 説明`
「この引数には、このデータ型（`number`＝数字など）を期待しているよ」とエディタに伝えています。
- `@returns {型} 説明`
「この関数が終わったとき、こういう型のデータが返ってくるよ」と教えてあげています。
もしあなたが VS Code を使っているなら、このコードを書いたあとに `calculateTotal(` と打ち込もうとすると、エディタがポップアップを出して「ここには数字を入れるんだよ！」と優しくガイドしてくれるようになります。
—
4. よくある「つまずきポイント」をそっとフォロー
初学者の頃は、型を意識し始めると思いがけない疑問が湧いてきますよね。現場で後輩からよく聞く質問に先回りしてお答えしておきます。
Q1. もし文字（文字列）を渡したいときはどう書くの？
A: `number` の代わりに `string` と書けばOKです！
/
- ユーザーに挨拶のメッセージを作るよ
- @param {string} name – ユーザーの名前
- @returns {string} 挨拶の文言
/
function createGreeting(name) {
return “こんにちは、” + name + “さん！”;
}
データ型の種類には、他にも真実（`true` / `false`）を表す `boolean` や、何もないことを表す `void` などがあります。まずは `number` と `string` の2つを仲良くなることから始めましょう。
Q2. 失敗したときに `null` が返るかもしれないときは？
A: 実務ではよくありますよね。「見つからなかったら `null`」みたいなパターン。そんなときは、パイプ（`|`）を使って「または」を表現できます。
/
- データベースからユーザーを探すよ
- @param {number} id – 探したいユーザーのID
- @returns {Object|null} 見つかったユーザー情報、いなければ null
/
schemaFindUser(id) {
// 処理がここに書かれていると想像してね
}
`{Object|null}` と書くことで、「オブジェクトか、もしくは null が返るんだな」とエディタも解析ツールも納得してくれます。
—
5. おわりに：完璧を目指さなくて大丈夫、まずは1行から
今回は、TypeScriptを導入しなくてもJavaScriptの品質をグッと高めてくれる `@param` と `@returns` について解説しました。
実務の現場でも、最初からすべての関数に完璧なJSDocを書いている人はいません。「あ、ここは複雑になりそうだな」「他の人（あるいは未来の自分）が迷いそうだな」と思った関数にだけ、そっと看板を立てる。それくらいの気負わないスタンスで十分なんです。
あなたの書いたコードが、エディタのサポートを受けてエラーを事前に防いでくれたとき、「おっ、ちょっとプログラミングが楽しくなってきたかも！」と感じてもらえたら、チーフアーキテクトとしてこれ以上の喜びはありません。
今日書くその関数に、ちょっとだけ「型」という名の優しさを添えてみませんか？
それでは、また次回の現場の知恵袋でお会いしましょう！
コメント