【Javascript】JSDocコメントの書き方、メリット

JavascriptでJSDocコメントを書く方法についてまとめました。

JSDocコメントとは

JSDocコメントとは、次のような「関数」「変数」の宣言前に次のようなコメントを書く記法です。

/**
 * 例示のための関数です
 * @param  {Number} x1 数学の点数
 * @param  {Number} x2 英語の点数
 * @return {Number}  数学と英語の合計点
 */
function Mytest(x1, x2) {
    /**
    * ユーザー名を格納するための変数です
    * @type {String}
    */
    var userName = '';

    return x1 + x2;
    };
}

JSDocコメントのメリット

JSDocコメントのルールにしたがってコメントを書くことで、次の利点が得られます。

メリット
1 プログラムの可読性が高まる(特にチームで開発する場合、生産効率の向上)
2 バグ防止(変数の型やオブジェクトの種類が明確になる)
3 JSDoc対応エディタを使うと、コーディングの補完が強化される

JSDocの基本ルールは「Google JavaScript Style Guide 和訳」で解説されています。
そのポイントを下記にまとめました。

プログラム全体の説明文

ポイント
1 先頭行は「/**」 + 「改行」 でスタート
2 途中は「半角スペース」 + 「*」 + 「半角スペース」+ 「説明文」
3 最終行は「半角スペース」 + 「*/」
/**
 * このプログラムはテストです。
 * Ver.1.1
 */

「関数」「変数」の説明文

/**
 * 例示のための関数です
 * @param  {Number} x1 数学の点数
 * @param  {Number} x2 英語の点数
 * @return {Number}  数学と英語の合計点
 */
function Mytest(x1, x2) {
    /**
    * ユーザー名を格納するための変数です
    * @type {String}
    */
    var userName = '';

    return x1 + x2;
    };
}

「配列」「連想配列」の説明文

/**
 * 〇〇の配列です
 * @type {Array}
 */
var myArray = [];
/**
 * 〇〇の連想配列です
 * @type {Object}
 */
var myObject = {
  "id": 1
  "name": "my text"
}

「クラス」「プロパティ」「メソッド」の説明文

/**
 * 〇〇のクラス
 * @constructor
 */
var myClass = function() {
  /**
   * 〇〇のプロパティ
   * @type {Number}
   */
  this.src1 = 0;
  /**
   * 〇〇のプロパティ
   * @type {String}
   */
  this.src2 = "";
}
 
/**
 * 〇〇のクラスメソッド
 * @param {Number} src1 メソッドの引数の説明
 * @return {Number} メソッドの戻り値の説明
 */
myClass.prototype.myMethod(src1) {
  return 0;
}
関連記事
1 【Cordova入門】Androidアプリ開発編
2 Javascript入門 サンプル集
3 Node.js入門
関連記事