Smart::Commentsでモジュールにサンプルコードを仕込む

ソースコードを読んでいると、関数の引数や戻り値の具体的な例がほしいと思うことがよくある。。そこで、実行可能なコメントを仕込むモジュールであるSmart::Commentsを使って、モジュール内にテストを兼ねたサンプルコードを仕込めばいいのではないかと考えた。これにより、開発者にとっては簡単なテストコードとして動き、読者にとっては具体例となるコードを簡単にソースコード内に埋め込むことができる。

package MyUtil;
use strict;
use warnings;
use parent qw(Exporter);
our @EXPORT = qw(add);

use if __FILE__ eq $0,
    'Smart::Comments';

### assert: add(10, 20) == 30
sub add {
    my($a, $b) = @_;
    ### add(a, b)
    ### a: $a
    ### b: $b

    return $a + $b;
}
1;
__END__

これで、このモジュールを直接実行するとSmart::Commentsが有効になり、関数の実行状態を印字すると共にassertによる保証が行われる。

$ perl MyUtil.pm
### add(a, b)
### a: 10
### b: 20

モジュールとして呼び出した際はスマートコメントはすべて通常のコメントとして扱われるため、パフォーマンス上の影響はない。
似たような目的をもったモジュールにTest::Inlineがあるが、Smart::Commentsはassertの他にもdumpなやforeachの進行の表示などデバッグ用の機能が豊富である。