【入門編】 @callbackによる関数シグネチャの定義 – JavaScript実践ガイド

こんにちは！フロントエンドの現場を渡り歩いてきた、ちょっとおせっかいなチーフアーキテクトです。

JavaScriptを書いていると、あちこちで「コールバック関数」に出会いませんか？
「ボタンがクリックされたらこれを実行してね」「データの読み込みが終わったらこの処理を動かしてね」というアレです。JavaScriptの世界では、関数に別の関数を渡すなんて日常茶飯事。これがいわゆる「高階関数（こうかいかんすう）」ですね。

でも、開発に慣れてくると、こんな不安やイライラにぶつかりませんか？
「あれ？このコールバック関数、引数に何を渡すんだっけ……文字列？それともオブジェクト？」
「うっかり `item.name` って書いたけど、本当は `item.title` だった！実行するまでエラーに気づかないよ……」

大規模なアプリになってくると、こういううっかりミスが原因のバグ探しで、何時間も溶かしてしまうなんてことはザラにあります。

そこで登場するのが、今回お話しする `@callback`（JSDocコメント） です！
TypeScriptを導入していなくても、いつものJavaScriptのままで、まるで強力なプロテクターをまとったかのように型安全を手に入れられる、実務の現場でめちゃくちゃ重宝するテクニックをご紹介しますね。

—

コールバック関数って、実は「お使いメモ」なんです

難しい言葉をいったん横に置いて、身近な例えで考えてみましょう。

あなたは今、お母さんから「スーパーでお使いをお願いね」と頼まれました。
そのとき、お母さんは口頭だけで「なんか適当に買ってきて」とは言いませんよね。普通は、こんな風にメモを渡してくれるはずです。

行き先: 近くのスーパー
買ってくるもの（引数）: 野菜の「名前（文字列）」と「個数（数字）」
お仕事が終わったら（戻り値）: 「買ってきたよ！」という完了のサイン（true/falseなど）

この「お使いのルールを書いたメモ」が、プログラミングの世界でいう「関数シグネチャ（関数の設計図）」です。そして、JSDocの `@callback` は、まさにこの「お使いメモ」をコードエディタ（VS Codeなど）に正確に伝えるための魔法のタグなんですよ。

—

実際に `@コード（JSDoc）` を書いてみよう！

百聞は一見にしかず。まずは、実際のコードを見てみましょう。
今回は、「お買い物の商品を1つずつチェックして、処理する高階関数」をイメージしてみます。

お買い物の商品を処理するコールバック関数の定義
@callback ItemCallback
@param {string} itemName – チェックする商品の名前
@param {number} itemPrice – 商品の値段（円）
@returns {boolean} 処理が成功したらtrue、失敗したらfalseを返す

カートの中身を順番に処理していく高階関数
@param {string[]} items – 商品名のリスト
@param {number[]} prices – 値段のリスト
@param {ItemCallback} callback – 1つひとつの商品を処理するお使いメモ（コールバック）

/
function processCart(items, prices, callback) {
console.log(“お買い物の処理を開始します！”);

for (let i = 0; i < items.length; i++) { const name = items[i]; const price = prices[i]; // ここで、上で定義したコールバック関数を呼び出しています const isSuccess = callback(name, price); if (!isSuccess) { console.log(`${name} の処理でエラーが発生しました……`); break; } } } どうでしょう？一見すると普通のJavaScriptですが、頭に書かれている謎のコメント（JSDoc）がポイントです。「難しそう……」と思いましたか？大丈夫ですよ！このコメントを書いておくと、私たちが普段使っているコードエディタ（VS Codeなど）が、このルールをしっかりと読み取ってくれるんです。 ---

エディタがあなたの「専属アシスタント」に変身する瞬間

この `@callback` を定義しておくと、実際にこの関数を使うときに、エディタがめちゃくちゃ優しいアシスタントのようにサポートしてくれます。

例えば、先ほどの `processCart` 関数を使うために、新しい関数を渡そうとタイピングし始めると……？

// カートのデータを用意
const cartItems = [“りんご”, “バナナ”, “みかん”];
const cartPrices = [150, 100, 80];

// processCartを呼び出してみる
processCart(cartItems, cartPrices, (name, price) => {
// エディタが「あ、ここには文字列と数字が入るんだな」と自動で理解して補完してくれる！
console.log(`${name} は ${price}円です。`);

return true; // 戻り値がbooleanであることもエディタが知っている
});

もし、あなたがうっかり「あ、そういえば商品の重さも知りたいから3つ目の引数として `weight` を使おう！」なんて書こうものなら、エディタが「おいおい、そんな引数はお使いメモに書いてないよ！」と、優しく（あるいは厳しく）赤波線で教えてくれます。

実行する前に間違いに気づける。これこそが、現場の開発スピードを爆上げする最大の秘訣なんです。

—

初学者がつまずきやすいポイントと「大丈夫だよ」のフォロー

ここで、よくあるつまずきポイントをいくつか先回りして解説しておきますね。

1. 「コメントの書き方が厳しすぎて、覚える気がしない……」

→ 全部を完璧に覚える必要は、全くありません！
最初は、`@callback` の書き方をコピペして使い回すところからで十分です。エディタが補完してくれる便利さを一度体験してしまうと、もうコメント無しの開発には戻れなくなりますよ。

2. 「これって、TypeScriptを使わないといけないの？」

→ いいえ、通常の `.js` ファイルのままで大丈夫です！
TypeScriptの環境構築をしなくても、VS CodeなどのエディタがJSDoc（`/ … /` のコメント）を読み取って型チェックをしてくれます。だから、「まずはJavaScriptのままで、少しずつ安全性を高めたい」という現場や学習の段階にドンピシャでハマるんです。

—

まとめ：お使いメモで、チームの未来を救おう

今回は、`@callback` を使った関数シグネチャの定義についてお話ししました。

`@callback` は、高階関数に渡す「お使いメモ（設計図）」である。
これがあることで、引数や戻り値のミスをエディタが事前に防いでくれる。
TypeScriptを導入していなくても、いつものJavaScript＋JSDocですぐに実践できる。

Web制作やプログラミングの学習を進めていると、「動くけれど、なぜ動くのか不安……」という状態に何度も出くわします。そんな時、今回のような型やシグネチャの知識を少しずつ味方につけていくと、コードを書くのがどんどん楽しく、自信が持てるようになっていきますよ。

明日からのコードには、ぜひそっと `@callback` という「お使いメモ」を添えてみてくださいね。あなたの開発ライフが、少しでもストレスフリーで楽しいものになりますように！