JSDocについてまとめる | Offers Tech Blog

こんにちは！🐯
プロダクト開発人材の副業転職プラットフォーム Offers を運営する株式会社 overflow のエンジニアの Taiga🐯 です。こちら の記事でキックボクシングを始めたものの、肩を痛めて療養中です。さて、今日は型の話です。

はじめに

エンジニアリング領域のみに関わらず、ドキュメントの必要性は言わずもがなだと思います。
仕様はまだしも、1 つ 1 つのメソッドに対してすべてコメントを残す^[1]のは難しいですよね。

とはいえ、機能が増えるにつれてコード量も増えることは避けられません。

先日、フロントエンド側のコードレビューで「JSDoc 追加すると Good^[2]」といったコメントを頂き、なにそれおいしいの^[3]状態だったため、二番煎じ感は否めませんが備忘録も兼ねて記事にしておきたいと思います。

JSDoc とは

そもそも JSDoc とはなんぞやということですが、ドキュメント を引用すると

JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.

とありますね。「JavaDoc や phpDocumentor に似た」とある通り、
Doc の文化自体が昔から存在する模様。
ちなみに、JSDoc は 1999 年が発リリースだったようです。

何が嬉しいのか

JSDoc を書くメリットについて、下記 3 点があります。

1. 将来ソースコードを読んだ際に(自分含む)、可読性の向上により生産効率の上昇に繋がります。
   → 実装しても数ヶ月後に「これどんなメソッドだったっけ」となることは誰しもあると思いますが、そういった有意義ではない時間を削減できます。
2. JavaScript で曖昧になりがちな型が明確になり、予期せぬ型エラーによるバグを防げます
   → 1 に近しいですが、実装を追っていって戻り値を推測する手間の減少に繋がります
3. エディタによっては、補完が効き開発効率の上昇に繋がります。
   → Visual Studio Code では、しっかりと補完が効きました。

デメリットとしては、書く工数が多少かかるのと、行数が増える。といったところでしょうか。

どうやって使うのか

例として、頻出するケースをまとめておきます。(コードは一部 ドキュメント を引用します)

@param

@param は関数の引数です。実際に定義された引数の数だけ @param を指定し、型も一緒に指定します。

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
 //省略
}

Represents a book とあるのは、この関数が何を返すかのアノテーションです。

@type

@type は変数の型です。JavaScript では TypeScript のような型注釈が利用できないため、このように記載すると型も定義可能です。

/**
 * limit of book
 * @type {Number}
 */
const BOOK_LIMIT = 20;

変数レベルだと説明したいことはないかもしれませんが、上記の様に Doc に書くと一瞬で理解できますね。

@return or @returns

@return は関数が返す値です。実際に行う処理を @returns の右記に書くのもありだそうです。

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @return {number} Sum of a and b
 */
function sum(a, b) {
 return a + b;
}

@return or @returns とありますが、どっちを使ってもいいそうです。しかし @returns は @return の別名とのことなので短い @return を使っていきたいです。

@see

@see は、他のオブジェクトや資料を示すものです。複雑性やドメイン知識などが絡んだ事象に関してはリンクとして書いておくといいですね。

/**
 * Both of these will link to the bar function.
 * @see {@link bar}
 * @see bar
 */
function foo() {}

// Use the inline {@link} tag to include a link within a free-form description.
/**
 * @see {@link foo} for further information.
 * @see {@link http://github.com|GitHub}
 */
function bar() {}

おまけ

Visual Studio Code に限った?話になりますが、 // @ts-check を js ファイルの先頭で有効にすると、
js ファイルを TypeScript のように構文チェックを行ってくれます。
実際は Visual Studio Code の目印というだけでありエラーがあっても JavaScript 的に OK であれば動いてしまいますが、
気軽に型チェックという意味では便利かと思います。

さいごに

今回紹介させて頂いたのは一例であり、より詳しく知りたい方は JSDocのドキュメント をご参照ください。

JavaScript だけでなく、Doc 文化(ドキュメントを残す意識)は各エンジニア及びチームでもっていくと、保守性の高い開発体制に繋がるのかな、と感じました。これからは言語問わずその意識を持ち開発していきたいと思っています!

関連記事

https://zenn.dev/offers/articles/20230213-communication-dilemma-for-engineer

https://zenn.dev/offers/articles/20230110-my_code_review_knowhow

脚注

1. コードにコメントを残すのかどうかの是非は一旦スルーするとして... 個人的にはこの考え方が好きです https://twitter.com/t_wada/status/904916106153828352

2. TypeScript なら型注釈があるので、必要性は薄まりますが...

3. 古いか..?w