コードリーディングにDoccoを使うと捗るかもしれない件

Doccoは、CoffeeScriptにコメントをつけてドキュメントを出力できるパッケージです。コードとコメントを左右に表示されるスタイルです。コメントにはMarkdownが使えます。

インストール

インストールはnpm。追加でPygmentsが必要です。

$ npm install -g docco
$ sudo easy_install Pygments

使い方

先日のエントリーで紹介したブログアプリCoffee-Boxを例にコメントを書くとこうなります。

(CoffeeBoxの紹介は 『Node.js「脱」初心者！CoffeeBoxでブログの作り方を学ぼう！』を参照してください）

# ***server.coffee*** は、Coffee-Boxのエントリーポイントです。
# [express](http://expressjs.com/)を読み込みます。
express = require 'express'
# Webサーバを生成します。
app = module.exports = express.createServer()

# config/configを読み込みます。
require('./config/config') app
# config/routesを読み込みます。
require('./config/routes') app

# Webサーバを起動します。
app.listen 3000

# サーバが起動したことを出力します。
console.log "coffee-box server listening on port #{app.address().port} " +
  "in #{app.settings.env} mode"

ドキュメントを出力してみます。docsディレクトリが必要なので作成します。

$ mkdir docs
$ docco server.coffee 
docco: server.coffee -> docs/server.html

左側にコメントに書いた内容が、右側にコードが表示されます。比較しながら読める点が新鮮です。

少し本格的にCoffeeBoxのconfig/config.coffeeにコメントを書いていきます。

# **config.coffee**では、[Coffee-Box](https://github.com/qiao/coffee-box)のWebサーバを設定します。

# [express](http://expressjs.com/)を読み込みます。
express      = require 'express'
# [connect-assets](https://github.com/TrevorBurnham/connect-assets)を読み込みます。
assets       = require 'connect-assets'
# [mongoose](https://github.com/LearnBoost/mongoose)を読み込みます。
mongoose     = require 'mongoose'
# lib/require_dirを読み込んで、オブジェクトとして保持します。
{requireDir} = require '../lib/require_dir'

# ```ROOT_DIR```を読み込みます。  
# ```#{hoge}```は、CoffeeScriptの String Interpolation（文字列挿入）です。  
# ```__dirname```は、Nodeが起動したディレクトリパスを示す定数です。 
ROOT_DIR = "#{__dirname}/.."

# Webサーバを設定します。
#
# 第1引数にexpressのWebサーバappを指定します。
module.exports = (app) ->
  app.configure ->
    # アプリケーションのversionを設定します。versionの情報は、[package.json](../package.json)に記述します。
    app.set 'version', require("#{ROOT_DIR}/package.json").version
    # [site.json](../config/site.json)に記述されたkeyとvalueをすべて設定します。  
    # CoffeeSciprtの for ... of 構文です。  
    # 例えば sitename というkeyに、**Name of your site**というvalueがappに設定されます。  
    app.set k, v for k, v of require("#{ROOT_DIR}/config/site.json")
    # libディレクトリをutilsとして設定します。
    app.set 'utils', requireDir("#{ROOT_DIR}/lib")
    # app/helpersディレクトリをhelpersとして設定します。
    app.set 'helpers', requireDir("#{ROOT_DIR}/app/helpers")
    # app/modelsディレクトリをmodelsとして設定します。
    app.set 'models', requireDir("#{ROOT_DIR}/app/models")
    # app/controllersディレクトリをcontrollersGetterとして設定します。
    app.set 'controllersGetter', requireDir("#{ROOT_DIR}/app/controllers")
    # expressのviewsディレクトリをapp/viewsに設定します。
    app.set 'views', "#{ROOT_DIR}/app/views"
    # テンプレートエンジンを[jade](http://jade-lang.com/)に設定します。
    app.set 'view engine', 'jade'
    # ビューのオプションとして、layoutを設定します。
    app.set 'view options', layout: "#{ROOT_DIR}/app/views/layouts/layout"
    # expressのloggerを使います。  
    # **loggerはミドルウェアで一番最初に設定すること**
    app.use express.logger('dev')
    # リクエストの```req.body```を読み込めるように設定します。
    app.use express.bodyParser()
    # HTTPのPUTやDELETEなどのメソッドをオーバライドできるように設定します。  
    # **この設定はbodyParserの前にすること**
    app.use express.methodOverride()
    # cookieを使えるようにします。
    app.use express.cookieParser()
    # sessionを設定します。  
    # secretキーに```settings.secretKey```を設定します。
    app.use express.session(secret: app.settings.secretKey)
    # [connect-assets](https://github.com/TrevorBurnham/connect-assets)を使います。
    app.use assets(src: 'app/assets', build: true, detectChanges: false, buildDir: false)
    # staticディレクトリをpublicに設定します。  
    # このディレクトリにはJavascript, CSS, HTMLなどの静的ファイルを格納します。
    app.use express.static("#{ROOT_DIR}/public")
    # routerを設定します。  
    # app.routerは、[server.coffee](server.html)で設定されています。
    app.use app.router
    # helpersを設定します。  
    # helpersはさっき設定しました。
    app.helpers app.settings.helpers
    # [express-messages](https://github.com/visionmedia/express-messages) をダイナミックヘルパに設定します。
    app.dynamicHelpers messages: require('express-messages')
    # session をダイナミックヘルパに設定します。 
    app.dynamicHelpers session: (req, res) -> req.session

  # 開発用の設定を指定します。
  app.configure 'development', ->
    app.use express.errorHandler(dumpException: true, showStack: true)

  # 製品用の設定を指定します。
  app.configure 'production', ->
    app.use express.errorHandler()

  # MongoDbに接続します。    
  # 接続先は```app.settings.dbpath```です。  
  # errが発生した場合、コンソールにエラー出力し、Coffee-Boxを終了します。
  mongoose.connect app.settings.dbpath, (err) ->
    if err
      console.error err
      process.exit()

これを出力した結果が以下の画像です。

Doccoはコードリーディングに最適

Doccoは、左右にドキュメントとコードを並べるスタイルが最大の特徴です。「何をしているかをコードと比較できる」点でコードを理解しやすいと感じます。リーディングしながらコメントを書いていき出力を繰り返すと、「どこまで自分が理解しているか」という進捗にもDoccoが使えます。また、Markdown形式でリンクや強調などの表現もできるので「着目している点や参考にしたリンク」も加筆できます。キレイなドキュメントで出力されるのでモチベーションも保てそうです。お試しあれ。