ドキュメントをどうするのか

ドキュメントを書かない理由

ドキュメントはそれがなくても正しく動いてしまうため、
プログラミングして成果物を動作させるという観点からすると後回しにしてしまいがちです。

そのため、実装とずれが出がちになり、出すぎると更新するのも嫌になってきます。

これも一つの割れ窓理論ですね。

そして、そうなるくらいなら、ドキュメントを書かずにPerlベストプラクティスを参考にきれいな実装をして
ドキュメントレスを目指そうとしていました。
実は単なる面倒くさがりなだけなんですよね。

達人プログラマーでもPerlベストプラクティスでもドキュメントの重要性が説かれているのに
それに目をつぶってまで、面倒くささを回避することの方が重視されていました。

心のどこかで、ドキュメントは重要なのに。と、後ろめたさでいっぱいです。

PODも単体テストに組み込みましょう

保守性の観点からもドキュメントは重要です。

この記事を読んでいる方は保守性の高いプログラムという言葉も好きな方だと思います。

保守性を高めるため、
頻繁に更新されるドキュメントを、
プログラミング作業とシームレスに

行う方法はないのか？

ありました。答えはpodの埋め込み+Test::Pod+Test::Pod::Coverageです。

まずは、Test::PodとTest::Pod::Coverageをインストールしてください。

あとは、

98_pod.t





-


use Test::More;
eval "use Test::Pod 1.14";
plan skip_all => "Test::Pod 1.14 required for testing POD" if $@;
all_pod_files_ok();

および、

99_pod-coverage.t





-


use Test::More;
eval "use Test::Pod::Coverage 1.04";
plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
all_pod_coverage_ok();

を、tディレクトリに放り込んで、MANIFESTに追記してください。
この状態でテストをはしらせると、

$ make test
PERL_DL_NONLAZY=1 /usr/local/bin/perl5.8.9 "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00_compile.t ....... ok
t/98_pod.t ........... ok
t/99_pod-coverage.t .. 1/1
#   Failed test 'Pod coverage on Foo::Bar'
#   at /usr/local/lib/perl5/site_perl/5.8.9/Test/Pod/Coverage.pm line 126.
# Foo::Bar: couldn't find pod
# Looks like you failed 1 test of 1.
t/99_pod-coverage.t .. Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/1 subtests

Test Summary Report



































-

















t/99_pod-coverage.t (Wstat: 256 Tests: 1 Failed: 1)
  Failed test:  1
  Non-zero exit status: 1
Files=3, Tests=3,  0 wallclock secs ( 0.03 usr  0.01 sys +  0.05 cusr  0.18 csys =  0.27 CPU)
Result: FAIL
Failed 1/3 test programs. 1/3 subtests failed.

    Error code 1
    
見事に単体テストでこけました。
これで、PODをちゃんと書かないと正しく動かなくなりましたね。（開発プロセスが）

これがイイんです。慣れると make test の Result: PASS が気持ち良くなってくるんですが、


実装する。
PODを正しく更新しないと気持ち良くなれない！
ちゃんとPODを更新する。
保守性が確保できる。
後ろめたくない。（開発に専念できる）１に戻る。
という、良いループができます。


    PODを書く
    では、PODを書きましょう。

まずは、Perlベストプラクティス（7.2 ひな形）を参考にして、適当に項目を選択しテンプレートファイルを作成します。

私はNAME,SYNOPSIS,DESCRIPTION,METHODS,SEE ALSO,AUTHOR,LICENCE AND COPYRIGHTを採用してます。
この辺は、慣れてから調整したらいいかなと思います。あんまり多いと書く気が失せますし。
またvimを使っていますので、Perlベストプラクティスにあったiabを設定しました。

NAMEのところで、今回の場合はFoo::Bar - モジュールの説明を書けば、

$ perl Makefile.PL PREFIX=~/local/perl
Checking if your kit is complete...
Looks good
Writing Makefile for Foo::Bar
前回と違って警告がでなくなりました。

$ make
cp lib/Foo/Bar.pm blib/lib/Foo/Bar.pm
Manifying blib/man3/Foo::Bar.3
$ make test
PERL_DL_NONLAZY=1 /usr/local/bin/perl5.8.9 "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00_compile.t ....... ok
t/98_pod.t ........... ok
t/99_pod-coverage.t .. ok
All tests successful.
Files=3, Tests=3,  0 wallclock secs ( 0.02 usr  0.02 sys +  0.08 cusr  0.15 csys =  0.27 CPU)
Result: PASS
すばらしい。テストが通りました。



    まとめ
    PODを書くことを開発プロセスに組み込むまでをまとめてみました。

実はまだ、よくわかっていないことも多くて、名前だけあって説明がない場合にエラーにするには、
all_pod_coverage_ok({nonwhitespace => 1});でいけそうな感じなんですがなぜかだめだったり、
継承しているときにドキュメントしていないのにOKになったりします。

でも、今まで書いていなかったことが書くようになったことは大きな前進です。

昨日より今日が良くなっていればとりあえずは良しとして今後の課題とします。