みなさんはコメントと言われてどんなものを想像するでしょうか？
// ここにコメントを残します
/*
* 複数業だとこんな感じ
* コメントを残します
*/
上記のようにコメントを残すことは多いと思います。
ただ、コメントを残すのではなくコーディングのヒントになるものを残せるのがベストです！
なので「JSDocコメント」について復習も兼ねてまとめてみました！
読んでくれた人が明日からJSDocコメント書いてみようと思えるようになることを目指した記事です！
JSDocコメントってなに？
JSDocコメントとは関数や変数の宣言前に記載するコメントです。
@typeや@paramを記述します！
/**
* @type {boolean}
* @param {string} name
*/
JSDocコメントの種類
JSDocコメントには先にあげた@typeや@param以外にたくさんあります！
よく使われるものを紹介します！
| JSDocの種類 | コメントの意味 |
|---|---|
@type |
値の型や説明を記述する |
@param |
関数の引数の説明を記述する |
@returns |
関数の戻り値を記述する |
@see |
資料を示し、合わせて確認してほしいものを示す |
@author |
開発者の名前を記載する時に利用 |
@deprecated |
非推奨であることを示すもの |
@function |
メソッドの定義であることを示す |
-
@seeは、具体的に言うとライブラリのリンクなどがコメントに記載されることが多い印象 -
@authorは役割分担の記録としても利用される -
@deprecatedはあまり見る機会がないですが、利用してほしくない関数に利用するものでリファクタリングの際に利用する -
@functionはメソッド、具体的にはアロー関数式で関数を書く場合に利用することが多い
JSDocコメントを書くと何が良いのか？
特に良いと思えるのは以下の点です。
- コンテキストの理解につながる
- コードヒントが表示されてドキュメントの替わりになる
コンテキストの理解につながる
JSDocで適切にコメントが書かれていることはコンテキスト（背景）の理解につがなります。
過去の開発はどのような判断でどのようなコードが書かれたのかが適切にコメントが残されていることによって理解が早まり、誤った設計や実装をしなくて済む手掛かりになると考えています。
コードヒントが表示されてドキュメントの替わりになる
vscodeなどのエディターでJSDocを記述してあると、コードヒントとしてポップアップが表示されるなどコードを書くときの手助けになってくれます！
例えば下記のようにコメントを書いたとします。
/**
* カウントの数値を取得します。
* @return {number} カウントの数値
*/
定義した関数の部分をホバーすると画像のようなポップアップが表示されます。
コメントをいただいて気がつきましたが、
APIドキュメントとしてのコメントとソースコードに対するコメントを切り分けておかないとコーディングの邪魔になってしまう可能性もあります…。
コメントする時は、コード内にすべきかドキュメントファイルとして切り分けて別で管理するかチーム内でコミュニケーションをとってください！
【まとめ】JSDocコメントについて
ここまで読んでくださった方はきっと明日からJSDocコメントを書いてくれると思います！
プロジェクトでは人の入れ替わりは常です。
わかりやすい、丁寧なコメントを残していきましょう！
適切でわかりやすいコメントを残すことは、後の開発生産性に大きく影響を与えると考えています！
コメントを書くとファイルのコード量が増える。というのも事実です。
ただ、今だとファイルを圧縮する方法はいくらでもあります。
コメントを書かずして、後の開発者に0からコードリーディングさせるのはあまりにも非効率なのでコードヒントが表示される状態にしておける方がメリットなのではないかと考えています。
コメントには皆さんもご存知の通り「why not」が書かれていることが重要です。
もちろんコメントを書くまでもなく綺麗で明瞭なコードを書けることが望ましいですが、さまざまな理由からそうできない場合も存在すると思います。
丁寧なコメントが残すことで、後の開発者により良い実装を依頼できるメッセージにもなると思います！
コメントを書く理由の1番は後の開発者にコンテキストを伝えることにあると思います。
私もわかりやすいコメントが記述できるように改めて意識していきます！