Moose/Mouse用フックメソッドをPod::Coverageの対象から外す方法

| コメント(0)

Moose/Mouseベースのクラスをテストする際には、本筋とは離れたところで一工夫が必要になることがあります。

例えば以前の記事「Arkアプリケーションの開発者テストでTest::Perl::Criticを使う」では、Test::Perl::Criticに於いて、use Mooseなどでuse strict構文も代替した場合でも、Perl::Critic::Policy::TestingAndDebugging::RequireUseStrictに引っ掛からないようにする方策を例示しました。

これに関連して、メソッド(やファンクション)についてPOD内での言及が網羅されているかを検査するTest::Pod::Coverageで、Moose/Mouse用の一部メソッドの記述を省いてしまいたい場合があります。

具体的なメソッドは、例えば

  • BUILDARGS()
  • BUILD()
  • DEMOLISH()

などのフックポイントです。

私は、PODというものはモジュールの使用者向けの資料であって、内部実装について開発者へ向けて事細かく書くような資料ではないと思っています。場合によりけりですが、基本的にはそうした考えに基づいてPODを書いているつもりです。

そうすると、例えばBUILDARGS()に於いてどのようなパターンで引数の読み替えをするか(例えばIntなスカラー値1つを渡されたら{ epoch => $value }に読み替えるなど)を書くよりも、素直にnew()についての記述を設けた方が良いということになります。

ということで、PODにそれらを書かずに、Pod::Coverage自体の機能を活用することで、「ためにする文書化」(手段の自己目的化)を避けることにしましょう。

all_pod_coverage_ok(
    {
        also_private => [qw(
            BUILDARGS
            BUILD
            DEMOLISH
        )],
    },
);

具体例としては、拙作DBICx::Modeler::Generatorの開発者テストであるxt/pod_coverage.tなどを挙げておきます。

なお、Kwaliteeを高くすることなどを目的とした「やせ我慢」について以下で補足しておきます。

嗚呼、やせ我慢

Kwalitee対策

ディストリビューションの品質を測る一指標であるKwaliteeを向上するためには、若干バッドノウハウ気味な工夫を強いられる場合があります。

例えば上記のuse strict絡みでは、Module::CPANTS::Analyse 0.85およびTest::Kwalitee 1.01の状態では、回避策を見出せませんでした。従って、冗長なようですがuse strict(とuse warnings)を明示的にコードに書くことで無理矢理都合を付けています。

Devel::Cover対策

Devel::Cover 0.64, Pod::Coverage 0.20, Test::Pod::Coverage 1.08の環境では、本稿で折角対策したはずのメソッド説明の省略が引っ掛かってしまいます。

ただ、これは何とか出来そうな予感がするので、時間のあるときにでも調べてみたいと思います。

やせ我慢は程々に

無理にバッドノウハウを重ねても、「ためにする対策」に陥ってしまいかねません。そうすると、無理のあるコードを書いてしまうことになります。

例えばDevel::CoverのPOD網羅率などは、BUILD()の説明を書くことによってドキュメントの焦点がぼやけてしまい、かえってユーザーにとって害をなしてしまうとも考えられませんでしょうか。

牧さん(lestrratさん)も『モダンPerl入門』p.234で

そもそも再現不可能な状況もあり得るのでカバレッジ100%という数値にこだわる必要はありません

と言明しているように、こうした箇所で無理に数値を稼ぐ必要はないはずです。

負担のない範囲で、かつ、将来に亘る保守を妨げない範囲に限って細々と対策することとして、その域を超えるような対策は素直に諦めるのが良いと思います。

脱・慈善事業

こうした「ためにする文書化」は、無駄で無益であるばかりでなくて有害ですらあります。仕事以外ではやりたくないですね。仕事でもやりたくないというのが本音ですが、私は建前を前面に押し出している小心者です。しかしながらこのブログの所在は会社に露見しているので、週明け頃に私の席が無くなっている可能性があります。

私も以前はこうした雇用創出的な意味合いすら透けて見える慣行(関連情報:「VBAを使うのはずるい」で有名な「マクロを組んで作業するのは実力ではないですか?」)を打ち破ろうとしたことがあります。開発・運用費の締め付けが厳しいという割に、こうした慈善事業を営むようなお茶目な会社ではいけない、筋肉質な会社にならなければならない、などと。しかし金融ユーザー系システム子会社というものは石橋を叩いても渡らないものなのか、私の説得力の欠乏によるものなのか、多分後者だとは思うのですが、ともかく諦めざるを得ないということがありました。

「ためにする文書化」を避けられる現場では、焦点を絞った文書化を是非試みてください。

コメントする

筆者"Gardejo"について

  • Twitter: @gardejo
  • GitHub: gardejo
  • CodeRepos: gardejo
  • CPAN: MORIYA

このサイトについて

Eorzea System Worksは、架空のシステム開発結社です。

FF14.name (FinalFantasyXIV.name)では、アヴァター(プレイヤーキャラクター)の管理システムやイベント出欠・リマインダシステムや、リンクシェル(LS)運営・管理システムやDKPシステムなどを設計・開発・公開する予定です。

関連サイト

関連サイトでは、他にもFF14に関連するサイトをいくつか紹介しています。

リンク, トラックバック歓迎

このブログへのリンク(どのページでも構いません)やトラックバックを歓迎します。

設計・開発・運用の参考にさせていただきますので、コメントもお気軽にお寄せください!

個別の記事に対するご意見などのほか、目安箱もご用意しています。

このブログ記事について

このページは、Gardejoが2009年12月 4日 02:14に書いたブログ記事です。

ひとつ前のブログ記事は「Perlクラスのアンロード方法(Class::Unload使用版)」です。

次のブログ記事は「備忘録: Orochiで依存の逆順にinject_classしないこと」です。

最近のコンテンツはインデックスページで見られます。過去に書かれたものはアーカイブのページで見られます。

2014年2月

            1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28  

やや真面目なサイト