JavaScriptを書いていて、こんなコメントを見かけたことはありませんか？
/**
*
*
*/
正直、最初は
「コメントが丁寧なだけ？」「なくても動くよね？」
と思っていました。
気になったので調べてみたところ、これは JSDoc（ジェスドック） と呼ばれるコメント記法でした。
この記事では「JSDocって何？」「何のために書くの？」を、自分なりにまとめてみようと思います。
JSDocとは？
JSDocは、関数が何を受け取り、何を返すのかをコメントとして明示するための記法です。
人間が読むためだけでなく、VS Codeなどのエディタにも情報を伝える役割があります。
引数を説明する例（@param）
例えば、タスクを追加する関数があるとします。
/**
* タスクを追加する
* @param {string} taskName
*/
function add(taskName) {
tasks.push({ name: taskName, isDone: false });
}
ここで書かれている
@param {string} taskNameは、
- この関数は taskName という引数を受け取る
- その型は string（文字列）
ということを表しています。
つまり 「どんな引数を受け取る関数なのか」 を明文化している、というわけです。
返り値を説明する例（@return）
次に、完了したタスク一覧を返す関数です。
/**
* 完了タスクの一覧を取得する
* @return {array}
*/
function doneList() {
return tasks
.filter(task => task.isDone)
.map(task => task.name);
}
この場合、@return {array}によって、
- この関数は値を返す
- 返り値は配列（array）
であることが分かります。
引数とは逆に、「この関数を呼ぶと何が返ってくるのか」 を示しています。
JSDocを書くメリット
JSDocを書くことで、次のようなメリットがあります。
①未来の自分・他人が理解しやすくなる
関数の中身を読まなくても、何を受け取るのか何を返すのかがコメントを見るだけで分かります。時間が経ったあとにコードを見返したときの理解速度が、かなり変わります。
②エディタ（VS Codeなど）が賢くなる
JSDocで型情報を書くと、VS Codeなどのエディタが補完を出しやすくなる、型の不整合っぽい箇所に警告を出してくれるといった恩恵があります。
JavaScriptなのに、少しTypeScriptっぽい安全性が手に入るイメージです。
③JavaScript → TypeScript移行の下準備になる
後からTypeScriptに移行したくなったときも、どの関数がどんな引数を受け取りどんな値を返すのかがすでに整理されている状態になります。
つまりJSDocは、「将来のためのドキュメント兼設計メモ」 としても機能します。
まとめ
最後までご覧いただきありがとうございました。