JavaScriptパターン #2

1人で読書会 JavaScript

必須パターン

高品質なJavaScriptコードを書くための必須パターンとコーディングの習慣。

なぜ?

バグ→修正するのにコストがかかる→時間が経つほどコストは高くなる

修正すべき問題が新しければ、問題を把握しやすいので見つけたら即修正がベスト。

コードを書くよりも読む方が時間がかかる。

コードの変更(新しい機能の追加、バグの修正、レビュー)で、コードを書いた当初よりも
変化したコードを読むのにはより時間がかかる。

保守しやすいコードを書く事が重要
  • 読みやすい
  • 一貫性がある
  • 見通しが良い
  • 一人で書いた様なコードに見える
  • ドキュメントが整備されている

APIのドキュメントを書く

  • YUIDoc
  • JSDoc Toolkit

もう少しシンプルで、個人用にも使えるようなものが良いなと思ったのでdoxを使ってみることにしました。

Doxのインストール

npmから

% npm install dox

git clone

% git clone https://github.com/visionmedia/dox.git
% cd dox
% make install
JavaScriptのコメントにタグを記入する
/**
 * Sample アプリケーションファイル
 *
 * @author daigo3
 * @version 0.1
 */
var MYAPP = {};

/**
 * ユーティリティ
 * @namespace MYAPP
 * @class util
 */
MYAPP.util = {
  hello: function(name) {
    return 'hello,' + name;
  }
};

/**
 * Personオブジェクト
 * @class Person
 * @constructor
 * @namespace MYAPP
 * @param {String} first ファーストネーム
 * @param {String} last ラストネーム
 */
MYAPP.Person = function(first, last) {
  this.first_name = first;
  this.last_name = last;
};

/**
 * フルネームを返す
 * @memberOf Person
 * @returns {String} 名前
 */
MYAPP.Person.prototype = {
  getName: function() {
    return this.first_name + ' ' + this.last_name;
  }
};

@param、@returnの様なタグはJSDoc Toolkitのタグに対応している-http://code.google.com/p/jsdoc-toolkit/w/list

APIドキュメントの生成
% dox --title MyApp app.js > myapp.html
... parsing 1 file(s)
... loading default style
... parsing app.js


こんな感じのmyapp.htmlが生成される