JSDocを使って多人数でも効率的な開発を行おう

一人でシステム開発している場合は概ね全体像が把握できているでしょう。しかし人数が増えてきてモジュールに分割して開発などを行っていると、それぞれどういった処理目的で作られているのか分からなくなってきてしまいます。そこでJavaの開発で多く利用されてきたJavaDocのJavaScript版、JSDocを使ってみましょう。

JSDocはhifiveの中でも実際に使われています。記述した内容はHTMLファイルへの出力も可能です。JSDoc: Namespace: h5のようにWebブラウザでシステム全体が分かるようになっています。

その他、以下のようなメリットもあります。

IDEの中でコーディング補助に使える

EclipseなどのIDEではJSDocの内容を読み取って補完処理を行う際に内容を表示してくれるようになります。これによりコーディングミスが防止できるようになります。

よく使うタグについて

実際、JSDocを記述する上で使われるタグは多くありません。以下の8種類だけ覚えてしまえばすぐに書けるようになります。

JSDocの書き方

サンプルは次のようになります。

/**
 * サンプルコントローラ
 *
 * @class
 * @name SampleController
 * @memberOf sample.controller
 */
var sampleController = {
  /**
   * コントローラ名(必須)
   *
   * @instance
   * @memberOf sample.controller.SampleController
   * @type String
   */
  __name: 'sample.controller.SampleController'
};

HTML出力

HTML出力を行う場合には jsdoc3/jsdoc を使って出力が可能です。

$ jsdoc yourJavaScriptFile.js

いかがでしょうか。開発ドキュメントはソースコードと共にある方がメンテナンスしやすく、参照も容易になります。また、補完入力に使えるなど開発効率の向上にもつながるでしょう。
また、例えばGoogleのClosure CompilerはJSDocに記述された型情報などに基づいて非常に高度なコード圧縮処理を行う機能を持っています（注：いくつかはClosure Compiler独自のタグを記述する必要があります）。先に述べたIDEとの連携を含め、様々なツールがJSDocの形式に対応しています。

今後ますます大型化するWebアプリケーション開発において、JavaScriptでもドキュメント整備が品質向上の鍵になるはずです。ぜひJSDocをお試しください。

また、さらに詳しくは08.ドキュメント記述・生成(JSDoc) – hifiveをご覧ください。

なお、実際の記述例は例えばGitHubのリポジトリ（hifiveのソースコードの一部）などでご覧いただけます。