【JSDocコメント】JavaScript で型ヒントを活用する方法とメリット

こんにちは。今回は JavaScript の開発でも耳にする「型ヒント(Type Hint)」についてお話しします。

JavaScript は動的型付け言語なので、数値や文字列、配列など、さまざまなデータ型を自由に扱えるのが魅力ですよね。ただ、一方で「型」について考慮しないと、実行時に思わぬエラーが発生したり、大規模開発で他のメンバーが困惑したりする可能性もあります。

そこで注目されているのが、型ヒントと呼ばれる仕組みです。今回は、この型ヒントとは何なのか、どのように導入すればよいのか、メリットや活用法をご紹介します。

そもそも型ヒントって何？

型ヒントとは、ソースコードの中で変数や関数、引数、戻り値などの型情報を明示的に書き込むことを指します。たとえば、下記のように「この変数は文字列だよ」「この関数の戻り値は数値だよ」といった情報を、コードのどこかに注釈として書き加えるイメージです。

多くの静的型付け言語（Java、C#、Go など）では型指定が必須ですが、JavaScript は動的型付け言語なので型を明示しなくても動きます。しかし、大規模開発やチーム開発でコードの可読性や保守性を高めるために、型ヒントを入れたいというニーズが増えているんですよね。

JavaScript で型ヒントを導入する方法

代表的な手法としては、TypeScript、JSDoc、そして Flow があります。それぞれ簡単に見ていきましょう。

1. TypeScript で書く

TypeScript は Microsoft が開発した JavaScript の上位互換言語です。JavaScript に型注釈を加えられるだけでなく、コンパイル時にしっかり型チェックしてくれます。

2. JSDoc コメントで型を記述する

「TypeScript を導入するほどではないけれど、最低限の型情報は欲しい」という方には、JSDoc を使った方法があります。

JSDoc は関数や変数の仕様をコメントで書いておくと、自動でドキュメントを生成してくれるツールですが、最近のエディタ（VS Code など）はこのコメントを読み取って簡易的な型チェックをしてくれるんです。

1. まず、関数の上に/**と入力してEnterキーを押してみましょう。

VSCodeなど多くのエディターでは、自動的にJSDocの雛形を作ってくれます！

/**
 * 
 */
function sayHello(name) {
  return "こんにちは、" + name + "さん！";
}

⬇️自動生成された雛形に内容を追加していきます

/**
 * 挨拶メッセージを返す関数
 * @param {string} name - 挨拶する相手の名前
 * @returns {string} 挨拶のメッセージ
 */
function sayHello(name) {
  return "こんにちは、" + name + "さん！";
}

2. パラメータの型は@と入力すると、@paramや@returnsなどのタグの候補が自動補完で表示されます

/**
 * ユーザーを登録する関数
 * @param {string} username - ユーザー名
 * @param {number} age - 年齢
 * @param {boolean} [isAdmin=false] - 管理者かどうか（省略可能、デフォルトはfalse）
 */
function registerUser(username, age, isAdmin = false) {
  // 処理内容
}

• @param {型} 名前 - 説明 の形式で書きます
• 省略可能なパラメータは [名前] と角括弧で囲みます
• デフォルト値があるパラメータは [名前=デフォルト値] と書けます

型を書いておくと、使う時に間違った型を渡すとエディターが教えてくれます。