JSDoc で JavaScript のコメントを書こう

カテゴリーから探す

年別から見る

2017/06/13

JSDoc で JavaScript のコメントを書こう

複数の人で開発を進める場合や、プログラムの規模が大きくなってきた場合に、
コメントの記述が、開発の大きな助けとなります。
さらにそのコメントが、標準化された方法で記述されていると、さらに可読性が高まり、
生産性の向上が期待できます。

私はこれまで、特にそういったことを気にせずにコメントを書いたり書かなかったりしてきましたが、
規模の大きな開発に関わるときに、このことが障害になってしまうことを感じ、
コメントの記述を見直そうと思い調べてみました。

今回紹介するのは、現在、最もポピュラーと思われる JSDoc コメントというコメントの記述方法です。
JSDoc コメントは、Google の JavaScript スタイルガイドでも推奨されているコメントの方法で、
AngularJS、CreateJS、jQuery（部分的に）など、メジャーなライブラリで利用されています。

JSDoc のメリット

プログラムの可読性が高まり、複数の人が関わる開発や、規模が大きなプログラムでの生産効率が高まる
JavaScript で曖昧になりがちな変数の型やオブジェクトの種類（配列、関数、コンストラクタ、クラスなど）が明確になり、予期しないバグの防止につながる
JSDoc に対応したエディタを使うことで、コーディングの補完が強化される

デメリット

コードが長くなるので、開発用とminifyした読み込み用のファイルに分ける必要がある
コメント記述のための手間と時間が必要になる

もちろん手間がかかるなどのデメリットもありますが、長い目で見れば、メリットのほうが大きいと考えられます。

基本的な記述方法 (Google JavaScript Style Guide を参照)


/**
 * [description]
 */

/**

* [description]

“/**” + 「改行」でスタート
途中は「半角スペース」 + “*” + 「半角スペース」記述
終わりは「半角スペース」 + “*/”

説明が長く、改行が必要な場合は、4つの半角スペースを文章の前に追加


/**
 * 長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明
 *     長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明
 */

/**

* 長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明

* 長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明長ーい説明

よく使うであろう記述の例

変数


/**
 * 例示のための変数です
 * @type {Number}
 */
var exampleVal = 20;

/**
 * [変数の説明が入ります]
 * @type {[変数の型が入ります(Boolean, Number, String など)]}
 */

/**

* 例示のための変数です

* @type {Number}

var exampleVal = 20;

/**

* [変数の説明が入ります]

* @type {[変数の型が入ります(Boolean, Number, String など)]}

配列


/**
 * 例示のための配列です
 * @type {Array}
 */
var exampleArray = [];

/**

* 例示のための配列です

* @type {Array}

var exampleArray = [];

連想配列


/**
 * 例示のための連想配列です
 * @type {Object}
 */
var exampleObject = {
  "id": 1
  "name": "exmaple text"
}

/**

* 例示のための連想配列です

* @type {Object}

var exampleObject = {

"id": 1

"name": "exmaple text"

}

より詳細に説明する場合は


***連想配列
/**
 * 例示のための連想配列です
 * @type {Object}
 */
var exampleObject = {
  /**
   * プロパティ id の説明です
   * @type {Number}
   */
  "id": 1,
  /**
   * プロパティ name の説明です
   * @type {String}
   */
  "name": "exmaple text"
}

***連想配列

/**

* 例示のための連想配列です

* @type {Object}

var exampleObject = {

/**

* プロパティ id の説明です

* @type {Number}

"id": 1,

/**

* プロパティ name の説明です

* @type {String}

"name": "exmaple text"

}

関数


/**
 * 例示のための関数です
 * @param  {Number} param1 引数の説明
 * @param  {Number} param2 引数の説明
 * @return {Boolean}       返り値の説明
 */
function exampleFunction(param1, param2){
  if(param1 > param2)
    return false;
  else
    return true;
}

/**

* 例示のための関数です

* @param {Number} param1 引数の説明

* @param {Number} param2 引数の説明

* @return {Boolean} 返り値の説明

function exampleFunction(param1, param2){

if(param1 > param2)

return false;

else

return true;

}

クラス（プロトタイプ）


/**
 * 例示のためのクラス
 * @constructor
 */
var exampleClass = function() {
  /**
   * プロパティの説明
   * @type {Number}
   */
  this.param1 = 0;
  /**
   * プロパティの説明
   * @type {String}
   */
  this.param2 = "";
}

/**
 * 例示のクラスのメソッド例
 * @param {Number} param1 メソッドの引数の説明
 * @return {Number} メソッドの戻り値の説明
 */
exampleClass.prototype.exmapleMethod(param1) {
  return 5;
}