JSDocコメントの書き方
JSDocは、JavaScriptコードに注釈を付けてドキュメントを生成するためのマークアップ言語です。JSDocコメントを使用することで、コードの可読性を向上させ、開発者同士のコミュニケーションを円滑にすることができます。
JSDocコメントの基本
JSDocコメントは、関数や変数の宣言の直前に記載します。先頭にアスタリスクを2つ記載し /** */ とし、型情報等を @ で始まるタグとともに記述します。
/**
* 数値を2倍にして返します。
* @param {number} num - 2倍にする数値
* @returns {number} - 2倍にした結果
*/
function double(num) {
return num * 2;
}
よく使うJSDocタグ
JSDocでよく使われるタグをいくつか紹介します。
| タグ | 説明 |
|---|---|
@param |
関数の引数を記述します。型情報とともに記述します。 |
@returns |
関数の戻り値を記述します。型情報とともに記述します。 |
@type |
変数の型を指定します。 |
@description |
関数や変数の説明を記述します。複数行に渡って記述することができます。 |
@example |
関数や変数の使用例を記述します。 |
JSDocのメリット
- コードの可読性向上
- 開発者同士のコミュニケーション円滑化
- ドキュメントの自動生成
参考資料
よくある質問
Q1: JSDocコメントはどの程度書くべきですか？
A1: プロジェクトの規模やチームの規約にもよりますが、基本的にはすべての関数やクラス、公開する変数にはJSDocコメントを記述することをおすすめします。特に、他の開発者が使用する可能性のあるコードには、詳細なJSDocコメントを記述することで、誤用を防ぐことができます。
Q2: JSDocコメントはどのように生成するのですか？
A2: JSDocコメントからHTMLドキュメントを生成するには、JSDocジェネレーターを使用します。JSDocジェネレーターは、npmなどでインストールすることができます。代表的なJSDocジェネレーターには、JSDoc 3があります。
Q3: TypeScriptを使用している場合はJSDocコメントは必要ですか？
A3: TypeScriptは型推論を備えているため、JSDocコメントで型情報を記述する必要性は低くなります。しかし、TypeScriptの型情報だけでは表現できない詳細な情報をJSDocコメントで記述することで、コードの理解を深めることができます。例えば、関数の動作や使用上の注意点を記述する際にJSDocコメントは役立ちます。
その他の参考記事:JavaScriptのコメント