Skip to content
Tags

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

by : 2015/02/25

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

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

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

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

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


よく使うタグについて

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

タグ 形式
@memberOf 名前空間名 or クラス名 どのプロパティに所属しているか定義する。
@name プロパティ名 プロパティ名を定義する。未指定の場合はコードで定義された名前がプロパティ名となる。また、@memberOfが指定されているとそのメンバに紐付く。
@namespace 名前空間を定義する。未指定の場合はメンバとして処理される。
@param {型名} 引数名 引数の名前と型が定義する。
@type 型名 変数の型を定義する。
@returns {型名} コメント 戻り値の詳細を定義する。
@class クラスとして定義する。
@instance インスタンスメンバとして定義する。記述しない場合はstaticメンバになる(@staticで明示的に指定することも可)。

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のソースコードの一部)などでご覧いただけます。

From → HTML5

現在コメントは受け付けていません。

%d人のブロガーが「いいね」をつけました。