Rubyベストプラクティス 第8章 上手なプロジェクトメンテナンス その2

第8章中盤です。Ruby製のプロジェクトのディレクトリ構成などの慣習について書かれています

  • README に書くこと
    • そのプロジェクトが何をするものなのか、概要
    • 簡単な使い方のドキュメント。詳細は API ドキュメントへ
    • 簡単なインストール方法
      • インストール方法にいくつか手段があるなどの時には INSTALL ファイルに分離
    • 作者へのコンタクト方法の記述
    • あまり README を長くしすぎない
  • ライブラリのレイアウト。以下のように lib の下にサブディレクトリとファイル1つの構成。lib/hoge.rb が深い階層のスクリプトを require する
lib/hoge.rb
    hoge
    • クラス/モジュールのネスト関係とディレクトリ構成/ファイル分割を対応付ける
    • 標準のクラスへメソッドを追加したり、1.8 との後方互換性のためのスクリプトなどは別途まとめて1つのファイルにすることもある→オープンクラスを利用する場所はまとめる
  • 実行ファイルは bin/ ディレクトリの下へ。$LOAD_PATH に "../lib" を加える
  • テストのディレクトリ構造。ライブラリとほぼ同様。最初の名前空間が1つなら省略することが多い
    • test_helper.rb とか spec_helper.rb ファイルを用意する
  • サンプルは examples ディレクトリに
    • サンプルはユースケースに基づいた分類を
    • サンプルはそのまま実行できるように $LOAD_PATH を整えるようにしておく

今日読んだプロジェクトのディレクトリ構成の慣習はいつも迷うところなのでこのようにまとめられているととても助けになります。

  • まずは Haml を例に上げてレビューしていく
    • README.rdoc に Haml とは何なのか、何に使えるのかが書いてある
      • これ超重要ですよね。README の先頭を見てそのプロジェクトが何なのか説明してないとよっぽど重要じゃないとそれ以上見る気がなくなりますもんね
    • README にインストール方法(まあ今なら gem でしょうけど)、使用例(これも重要。ドキュメントが rdoc だけだとぱっと使いかたがわからない)が書かれている
    • rdoc で API ドキュメントを自動生成している
    • rake でタスクを自動化している
    • テストがある
      • テストのディレクトリ構成が一貫している(Haml::Engine のテストは test/haml/engine_test.rb に)
      • テストを見るとライブラリの利用方法がわかる
    • VERSION ファイルにバージョン番号を格納

今日は Haml の例を見るところまでです。