書式プラグインテンプレート共通化のソースコード読ませてもらいました。 (m2w-dev) - mail2weblog（高機能メール投稿型モブログ）

バナナさん。

トゥイーです。

基本コンセプトの認識のすり合わせができたところでバシバシ行きますよ！＾＾

なるだけ重要と思う順番に書きます。

１．テンプレートの適用部分も含めて共通化して欲しいです（今は img 書式プラグイン内に存在していますね？）。

他の書式プラグインからも利用できるようにしたいからです。
書式タグ内でテンプレートと言えばこれという感じにしたいです。

２．テンプレートファイルの位置はカスタマイズできるようにしてください。

デフォルトは 02_conf/template などが良いかと思います。
ユーザが設定する場所は一ヶ所にまとめておきたいです。
また、カスタマイズできるようにしたいという意図には、
自動テストする際に変更できた方が良い（テストケースのフォルダを指定する）という考えも含まれています。

３．Dir.chdir は使わないでください。

副作用があるので、他の処理部分への影響が出てしまいます。
処理をした後に再度 Dir.chdir をするというのもダメです。
する必要がないようにできるはずです。
この考え方は、スレッドセーフにもつながります。

４．template_XXX というファイル名は冗長では？

まず認識の確認です。
現在、template フォルダにいくつかファイルが入っていますが、
template_img1.tmpl だけが有効という認識は合っているでしょうか？

img1.html ⇒ template_XXX という命名規則に合っていないので適用できない。
template_img2.img ⇒ 内容的に埋め込みを行なっていないのでテンプレートとして不完全。
template_img2.img はテンプレートの内容的なものなのでとりあえず良いです。

もし認識があっていればすべてのファイルに template_ という接頭詞を付ける必要があります。
template フォルダとして明確にテンプレートを分けているのだから、
template_XXX という命名規則は冗長なのでもっと短く書けた方が嬉しいと思います。

５．ドキュメントを書いてください。

共通部分の仕様を固めたらドキュメントにして wiki に書いて下さい。
場所は以下ページの

howto/develop/plugin/format

慣習辺りが良いと思います。詳細は、配下にページを作ってリンクで飛ばし、

howto/develop/plugin/format/template

に書くという感じが良いのではと個人的には思っています。
その際、テンプレートファイルは必ず UTF-8 にしてくださいという一文も必要だと思います。
システム内部は UTF-8 で統一しているので、

http://sourceforge.jp/projects/mail2weblog/wiki/howto%2Fdevelop%2Fencoding

それ以外のエンコーディングのファイルを入れるとたぶんおかしくなります。

６．テストを書いてください。

テンプレート部分を共通化したら、テストコードを書いてみてください。
以降、リファクタリングを行う際もバグの混入等を気にする必要がなくなります。
ソースの長期的な保証を行う意味も含んでいます。

test/m2w_plugin/format/test_format_plugin_utils.rb

への追加が良いのではと思います。

７．修正履歴的なコメントは最終的に消してください。

僕はちょっとコメントを書かなすぎという面はありますが…。少なくとも履歴をコメントに書くつもりはありません。
Subversion コミット時にコメントを書いてください。
コメントには以下を重視して書いてください。

・処理の塊に説明が必要な場合（分かりやす名前を付けてメソッドをわけるという代替も考えて下さい）
・特別な制約（例えばセキュリティ／信頼性／性能等）があり、それを達成する目的で重要な処理をしている場合

今のところメソッド毎の説明はあまり書いていません。
最初は書こうとした時もあったのですが、
リファクタリングでメソッドのインターフェイスが変わる場合があるので
その際の修正コストを下げるためです。

基本は Wiki にインターフェイスの考え方を書いています。
僕の場合、クラス図程度は、ノートに都度書いています。
自分で作ったものなのでパパっと書けてしまうということもありますが…。
クラス構成はたまに変わる場合があります。
特に次回の HTML メール（デコメール）対応でも少し変えます。
クラスの関係はそのうちちょこっと書くかもしれません。
その場合、graphviz を使って書こうかと思っています。編集も楽ですし。
graphviz 知ってますか？

８．スペースではなくタブ（２個スペース分）で統一したいと考えています。

９．余計な空行は削除願います（img.rb 下部）。

もちろん、処理の区切りをわかりやすくするための空行は適宜入れます。
プログラムの見やすさは理解の速度を早めるので、
タブの入れ方もそうですし、空行の入れ方にも気を配って配って下さい。

１０．ファイルは開いたら閉じてください。

Ruby の慣習としてはブロックを使って処理をします。

buffer = open(ファイル名, 'rb') do |file|
  file.read
end

これでファイル全部を読めると思います。
また、ブロックを使うとファイルのクローズも自動でしてくれます。

また、エンコーディングの指定もしてしまった方が安全です。

buffer = buffer.encode(M2W_SYSTEM_INNER_ENCODING, M2W_SYSTEM_INNER_ENCODING)

Ruby は文字列毎にエンコーディング情報を持っています。
意外とこれが厄介で、異なる文字エンコーディングを結合しようと思うとエラーが発生します。
バイナリー（open 時の b 指定）で読んでおいて、エンコード指定を行なっておくのが基本です。

質問は気軽にＯＫです！！！

----
トゥイー（伊藤 豊）：toy****@ownwa***** もしくは m2w_refer****@ownwa*****
高機能メール投稿型モブログサービス（β版）:http://www.ownway.info/mail2weblog/

[m2w-dev] 書式プラグインテンプレート共通化のソースコード読ませてもらいました。