JavaScriptで関数にコメントする標準的な方法とは？JSDocの基本と書き方

JavaScriptで関数にコメントを記述する際の事実上の標準は、JSDocと呼ばれる記法です。JSDocは、関数の目的・引数・戻り値などを構造化された形式で文書化するためのもので、多くのエディタやドキュメント生成ツールが対応しています。

JSDocの基本的な書き方

関数の直前に、/** で始まり */ で終わるブロックコメントを記述します。各行はアスタリスク（*）で始めるのが一般的なスタイルです。以下は、2つの数値を加算する関数へのJSDocコメントの例です。

/**
 * 2つの数値を加算します
 * @param {Number} num1 - 1つ目の数値
 * @param {Number} num2 - 2つ目の数値
 * @return {Number} num1とnum2の合計
 */
function sum(num1, num2) {
    return num1 + num2;
}

よく使われるJSDocタグ

JSDocでは、アットマーク（@）で始まるタグを使って関数の情報を記述します。主なタグは以下の通りです。

• @param … 引数の名前・型・説明
• @return（または @returns）… 戻り値の型と説明
• @description … 関数の概要
• @example … 具体的な使用例
• @throws … スローされる可能性のある例外
• @deprecated … 非推奨であることの明示

JSDocを使うメリット

1. エディタによる入力補完と型チェック

VS CodeなどのモダンなエディタはJSDocコメントを解析し、引数の型や戻り値に基づいた高度なコード補完や誤用の警告を提供してくれます。

2. ドキュメントの自動生成

JSDocツールを利用すれば、コメントからHTML形式のAPIリファレンスを自動生成できます。コードとドキュメントが乖離しにくくなる点も大きな利点です。

3. チーム開発での可読性向上

関数の仕様が統一された形式で記述されるため、コードレビューや保守、引き継ぎがスムーズになります。

まとめ

JavaScriptで関数にコメントする標準的な方法はJSDoc記法です。@param や @return などのタグを使って関数の情報を構造的に記述することで、開発効率とコード品質の両方を高められます。特にチーム開発や長期運用するプロジェクトでは、積極的に活用したい記法といえるでしょう。