コードの補足を行うためのコメントですが、書き方は人それぞれです。
しかし、自由なフォーマットでコメントを書くよりも、一定のルールに沿ったコメントを書くことで、プログラムの可読性が向上します。

そこで今回は、実際の開発現場などで使われるJSDocコメントについて解説していきます。

JSDoc

JSDocとは、JavaScriptで書かれたコードに注釈を追加するためのマークアップ言語です。かんたんに言うと、コメント記法の一つです。

多くの開発現場では複数人で開発を行うため、自分だけでなく他人が読めるコードが書けなければいけません。それはコメントも同様です。

しかし、コメントが統一化されていなければ、他人が読みやすいと思うコメントの基準も分からず、結果的に可読性にも影響が出やすくなります。
チームやプロジェクトによってコメントの書き方が異なるのであれば、尚更ハードルが高いです。

そこで多くの開発現場では、記述方法がルール化されているDoc機能を使って、可読性を高めます。
Doc機能は、各プログラミング言語で存在し、JavaにはJavaDoc、RubyにはRDocなどが用意されています。JavaScriptの場合はJSDocを使用します。

JSDocコメントの書き方

JSDocは、/** */のように先頭にアスタリスクを2つ記述するような形でコメントを表現します。/** と*/の間にコメントを記述し、項目分*を増やします。

/**
 * 記述
 * 記述
 * /

変数や関数の宣言の前に記述し、値の型や何のための変数であるかなどの説明を行います。
以下は、数値型の変数に対するコメントの例です。

/** 
 * @type {number} 年齢 
 */
let age = 30
  • @type：変数の型を表すタグ
  • {number}：型名（この場合は数値型）
  • 年齢：変数に対する説明

このように、コメントで説明したい項目を表すタグ、タグに対する値、またその補足を行う形で構成されます。

代表的なJSDocコメント

ここでは、現在JSDocでサポートされているタグの中から代表的なものを取り上げます。

@type

@typeは、変数の型を示します。
@typeの後ろのブラケット{}に、変数の型を指定し、その後ろに変数の説明を記述します。

/** 
 * 例　文字列型
 * @type {string} メッセージ
 */
let message = 'Hello!';

/** 
 * 例　数値型
 * @type {number} 年齢
 */
let age = 30;

/** 
 * 例　配列
 * @type {number[]} 年齢のリスト
 */
let ageList = [20, 30, 40];

/** 
 * 例　オブジェクト
 * @type {{id: number, age: number}} ユーザーデータ
 */
const user = {
  id: 1,
  age: 30
};

@paramと@returns(@return)

@paramは関数の仮引数（パラメーター）、@returnsは関数の戻り値です。@returnsは@returnと記述することも可能です。
@typeと同じ構文で各値に対する型や説明を記述しますが、パラメーターを追加で記述します。

/** 
 * @param {number} a 数値パラメーター
 * @param {number} b 数値パラメーター
 * @returns {number} 2つの数値を足した結果
 */
function add(a, b) {
  return a + b;
}

角括弧[]で仮引数を囲むことで、仮引数を任意のものとして指定することもできます。

/** 
 * @param {string} [name] - 任意の文字列パラメーター
 * @param {number} [age=30] - デフォルト値を持つ任意の数値パラメーター
 * @returns {number} 結果
 */
function add(name, age = 30) {
  return `${name}さんの年齢は${age}歳です`;
}

また、関数では、コメントの一番上にどのような関数であるかかんたんな説明を書くこともあります。

/** 
 * 画像のスライドショー
 * @param ...
 * @returns ...
 */
function changePics(pic) {
  return...
}

@author

@authorは、開発者の名前を記述するために使用します。
同じプログラムを複数人で作成している際に、役割分担の記録として使うと便利です。

/** 
 * @author Hanako Yamada
 */
function sayHi() {
  ...
}

@see

@seeは、他の資料を示します。作成したプログラムに関する参照資料がある際に使うと良いでしょう。

/** 
 * @see https://sample.com/
 */
function sayHi() {
  ...
}

JSDocとエディター

JSDocに対応しているエディターを使用すると、開発の効率が上がります。
例えば、VSCodeで以下のコードとコメントを書いてみます。

/** 
 * @param {number} a 数値パラメーター
 * @param {number} b 数値パラメーター
 * @return {number} 2つの数値を足した結果
 */
function add(a, b) {
  return a + b;
}

その後、関数にマウスのカーソルを合わせると、関数に対して記述したJSDocコメントが表示されます。

jsdoc

このように、各引数や戻り値の型など、関数の仕様をすぐに確認することができます。

JSDocはすべてのエディターに対応している訳ではありませんが、VSCodeやWebStormは、JSDocコメントに対するヒント表示やコードの補完機能があり開発環境としては優れているため、使ってみると良いでしょう。

まとめ

今回は、JSDocコメントについて解説しました。

JSDocコメントは、開発工程での効率化だけではなく、開発後のコードメンテナンスの際にも役に立ちます。
コメントがルール化されることで、上級者だけでなく初級者にとっても恩恵を受けられるため、まずは練習としてぜひ導入してみてください。

コメントの関連記事

・コメントの書き方
・良いコメントを書くためのポイント