JavaScriptでJSDocコメントを書くメリットとは

28
88

皆さんはJavaScriptでのJSDocコメントを利用していますか? JSDocコメントとは関数や変数の宣言の直前に/** ◯◯ */を書く記法のことです。自由なフォーマットでコメントを書くよりもルールに沿ったコメントを書くことで、プログラムの可読性が高まります。本記事ではJSDocコメントの使い方と導入のメリットを説明してきます。

JSDocコメントの書き方

JSDocコメントは関数や変数の宣言の直前に記載します。先頭のアスタリスクを2つ記載し/** ◯◯ */とし、型情報等を@type@paramというキーワードとともに記述します。

/**
 * スマートフォンのアクセスであるかを示す真偽値です。
 * @type {boolean}
 */
var isSmartphoneAccess = true;

/**
 * ページの一番上までスクロールします。
 * @param {number} duration スクロール時間のミリ秒です。
 */
function moveTop(duration) {
  // anything...
}

この仕組みは他の言語でも存在し、Java言語だとJavadoc、ActionScript 3.0だとASDocが知られています。JavaScriptのコーディング規約「Google JavaScript スタイルガイド - 日本語訳」でも、「すべてのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです」と推奨されています。

JSDocコメントのメリット① コードヒント/コード補完の表示

JSDocコメントはコード入力時にツールチップでコードヒントが表示されます。関数のコメントが表示されるため、関数の命令の内容を確認しながら安心してコードを書くことができます。次の動画のようにWebStormでは、プログラムのコードヒントの表示や補完入力の手助けとなっています。

ただし、どのエディターでもJSDocコメントに対応しているわけではありません。各種エディターのJSDocコメントの充実度を表にまとめました。筆者が試したところ、開発環境としてWebStormVisual Studioがとくに優れており、ツールチップにJSDocコメントの情報がすべて表示されました。無料のAdobeのBracketsも少しサポートされていて、JSDocコメントの型指定も表示してくれます。対してSublime TextAtomはサポートが十分ではありませんでした。

※ 上図はクリックで拡大できます

ちなみにAngularJSCreateJSReactなどのメジャーなJSライブラリにおいても、そのソースコードではJSDocコメントが使われています (例 : AngularJSCreateJSReact)。minifyされる前の(開発者向けの) JSライブラリを使えば、コードヒントとコード補完を表示できます。APIが多岐に渡るJSライブラリを利用するとき、わざわざリファレンスをブラウザで開いたり解説書で調べることなく、コード上で関数の仕様を確認できます。これはminifyされる前の(開発者向けの) JSライブラリを使うメリットの1つとしてあげられるでしょう。

▲描画ライブラリCreateJSのAPIを表示したもの

JSDocコメントのメリット② APIリファレンスの生成

yuidocjs等のツールを使うことでコードのリファレンスドキュメントを作成できます。こういったJSライブラリのリファレンスはみなさんも一度は見たことがあるのではないでしょうか。

Webサイト案件のソースコードでAPIリファレンスを作ってみると、どれだけコメントを丁寧にかけているか客観的に確認することができ案外面白かったりします。JSライブラリの開発者でなければAPIリファレンスを作ろうと思うことが少ないかもしれませんが、JavaScriptのスキルセットの1つとして覚えておくといいでしょう。

JSDocリファレンスを作成するには、続編記事「たった3ステップでできる! gulpでJSDocコメントからHTMLを自動書き出しする方法」を参考ください。

JSDocコメントのサンプル

JSDocコメントを使わずに書かれたJavaScriptを、JSDocコメント有りのJavaScriptと見比べてみましょう。まずはシンプルなコメントのコードです。

// カウントを管理するオブジェクトです。
function CountManager() {
  // カウントの数値です。
  this._count = 0;

  // カウントの数値をインクリメントします。
  this.addCount = function() {
    this._count++;
  };

  // カウントの数値を取得します。
  this.getCount = function() {
    return this._count;
  };
}

これをJSDocコメントとして書いてみます。// ◯◯として記載していたコメントを/** ◯◯ */の記法に変更し、引数の型なども含めて細かく指定します。

/**
 * カウントを管理するオブジェクトです。
 * @constructor
 */
function CountManager() {
  /**
   * カウントの数値です。
   * @type {Number}
   */
  this._count = 0;

  /**
   * カウントの数値をインクリメントします。
   */
  this.addCount = function() {
    this._count++;
  };

  /**
   * カウントの数値を取得します。
   * @return {Number} カウントの数値
   */
  this.getCount = function() {
    return this._count;
  };
}

もしJSDocコメントの引数や戻り値、型指定を面倒に思った方はWebStormに備わっているJSDocを自動的に生成する機能も利用するといいと思います。詳しくは宇都宮さんの当サイトで紹介されていますので、ぜひご覧ください。

まとめ

弊社では数万行〜数十万行のコードの開発案件が多いのですが、このボリュームになるとJSDocコメントの記載は必須となります。他の開発者が開発したJSモジュールと連携するときや、開発後の保守として数ヶ月前に記載した自分のコードを見返すときに、JSDocコメントで書かれていればクラス・メソッド・プロパティを素早く理解するのに役立ちます。

JSDocコメントのメリットは初級者から上級者まで受けられます。プロジェクトの大小問わず可能な限りJSDocコメントでコメントを書いてみてはいかがでしょうか?

※この記事が公開されたのは4年4ヶ月前ですが、 平成28年7月25日に内容をメンテナンスしています。