こんにちは！フロントエンド・アーキテクチャの現場を長年歩んできた私ですが、今日はJavaScriptのコードを書くときに誰もが一度は直面する、ちょっとした「優しさ」のお話をさせてください。
JavaScriptの世界へようこそ！毎日コードを書いていると、「あれ、この関数を呼び出すとき、この引数って毎回渡さなきゃいけないんだっけ？」と手が止まる瞬間、ありますよね。
特に、チームで開発をしていたり、未来の自分が数ヶ月後にそのコードを見返したりしたとき、「この引数は省略しても大丈夫なやつだっけ…？」と冷や汗をかくことは、プロのエンジニアでも日常茶飯事です。
そんなとき、コードを書く自分にも、それを使う仲間にも「ここは省略してもいいんだよ」とそっと教えてくれる、魔法の記法があるんです。それが今回お話しする JSDocにおける省略可能引数の定義（`[ ]` ブラケット記法） です。
難しく考えすぎなくて大丈夫ですよ。今日は、身近なお買い物のイメージと一緒に、優しく紐解いていきましょう！
—
そもそも「JSDoc（ジェイエスドック）」ってなに？
JavaScriptは、型が自由奔放（動的型付け）なところが魅力である反面、「どんなデータが来ても受け入れちゃう優しさの裏返し」で、時にバグの温床になりがちです。
そこで登場するのが JSDoc です。これは、JavaScriptのコードの「説明書」をコメントとして書くための書き方のルール。Visual Studio Code（VS Code）などのエディタは、この説明書を読んで「おっ、この関数にはこういうデータを渡すんだね！」と理解し、私たちがコードを書くときにピョコッとヒント（補完機能）を出してくれます。
つまり、JSDocを書いておくと、未来の自分が絶対に助かるんです。
—
カートの中身を思い浮かべてみてください
想像してみてください。あなたは今、ネットショップでお買い物をしています。
商品を買うとき、「商品名」は絶対に必要ですよね。でも、「ギフトラッピング（プレゼント用の包み）」はどうでしょう？ 「今回は自分用だからいらないや」というときは、ラッピングの指定は省略できますよね。
JavaScriptの関数もこれとまったく同じです。
- 必須の引数: 必ず渡さないとお会計が進まない「商品名」
- 省略可能な引数: なくても成立するけれど、あれば便利（または特別な処理をする）な「ギフトラッピング」
これをJSDocでどう表現するのか、次のセクションで実際のコードを見てみましょう。
—
ブラケット `[ ]` で「お留守番OK」を伝える
JSDocの中で「この引数はなくても怒らないでね（省略可能だよ）」と伝えるには、引数名を 大括弧（アークまたはブラケット） `[ ]` で囲むだけです。
百聞は一見に如かず。実際にコードを見てみましょう。
/
- ユーザーの挨拶メッセージを作る関数
- @param {string} name – 挨拶する相手の名前（これは絶対に必要！）
- @param {string} [greeting=”こんにちは”] – 挨拶の言葉（省略可能！指定しないときは「こんにちは」になります）
- @returns {string} 完成した挨拶のメッセージ
/
function createMessage(name, greeting) {
// もし greeting が渡されなかったら（undefined だったら）、デフォルトの言葉を使うよ
const words = greeting || “こんにちは”;
return `${words}、${name}さん！`;
}
// パターン1：名前だけを渡す場合（2番目の引数を省略）
console.log(createMessage(“田中”));
// 出力: こんにちは、田中さん！
// パターン2：名前も挨拶の言葉も両方渡す場合
console.log(createMessage(“鈴木”, “おはよう”));
// 出力: おはよう、鈴木さん！
どうですか？ JSDocの `@param {string} [greeting]` の部分に注目してください。`[ ]` で囲まれているのがわかりますよね。
エディタはこの `[ ]` を見つけると、「あ、2番目の引数はパスしてもエラーじゃないんだな」と理解し、私たちがこの関数を使おうとしたときに「2番目はなくても大丈夫だよ」と優しく教えてくれるようになります。
—
つまずきやすいポイント：省略したときの「初期値」はどうする？
ここで、初心者の人がよく「あれ？」とつまずきやすいポイントをこっそりシェアしておきますね。
JSDocで `[greeting]` と書いても、それだけでJavaScriptのプログラムが自動的にデフォルトの言葉（この場合は「こんにちは」）をセットしてくれるわけではありません。
JSDocはあくまで「エディタに向けたお手紙（説明書）」なので、実際のJavaScriptのコード側（関数の内部）でも、「もし引数がなかったら、代わりにこれを入れてね」という備え（デフォルト値の設定）をしてあげる必要があります。
近年のモダンなJavaScript（ES6以降）では、もっとスマートな書き方もありますよ。
/
- ユーザーの挨拶メッセージを作る関数（モダンな書き方）
/
function createMessageModern(name, greeting = “こんにちは”) {
// 関数の引数のところで直接「= “こんにちは”」と書いておく！
return `${greeting}、${name}さん！`;
}
このように、関数の引数のところで直接初期値を指定してあげつつ、JSDoc側でも `[greeting]` と書いておく。この2つをセットで行うのが、現場のプロがよく使う「丁寧で美しいコード」の作法です。
—
まとめ：怖がらなくて大丈夫、少しずつ慣れていきましょう
今回は、JSDocにおける省略可能引数の定義についてお話ししました。
- 引数を `[ ]` で囲むと、JSDoc上で「省略可能」であることを示せる。
- エディタの補完やヒント機能が賢くなり、開発がぐっと快適になる。
- 実際のJavaScript側でも、引数がなかったときの対策（デフォルト値など）を忘れないであげる。
最初は「覚えることが多くて大変だな…」と感じるかもしれませんが、すべてを完璧にこなす必要はありません。まずは「あ、この引数はなくてもいいや」と思ったときに、JSDocの中で `[ ]` で囲む癖をつけてみてください。
あなたの書いたコードが、未来のあなたや、一緒に働く仲間の笑顔を少しでも増やせますように。
フロントエンドの旅を、これからも一緒にマイペースに楽しんでいきましょう！
コメント