Daikuにpull-requestした話あるいはなぜドキュメンテーションをpull-requestするのかという話

先日、PerlモジュールのDaikuにpull-requestしたところ、無事マージされ、リリースされた。 songmuさん、ご対応ありがとうございます。

今回のpull-requestではそれなりの量のドキュメンテーションを追加させていただいた。思い返すと、自分は以前にもAnyEvent::MQTTとかSQL::Makerとかにちょっとしたドキュメントを突っ込んだりしていて、ドキュメンテーション目的のpull-requestが多い気がする。

自分の場合、Perlモジュールへのドキュメンテーションpull-requestは「そのモジュールの仕様を固めてもらう」ためにしている。

ドキュメントに書かれていない使い方で他人の書いたモジュールを使うのは自分にとってとても恐ろしいことで、極力避けている。たとえ今、そういった使い方ができても、ある日突然できなくなってしまう可能性があるからだ。逆に、ドキュメントに書いてある使い方であれば、ある程度後方互換性が保証された仕様とみなせるので、安心して使うことができると考えている。 (とはいえ、このへんの互換性の感覚はCPAN authorやモジュールごとに温度差がありそうではあるが)

したがって、あるモジュールに自分の使いたい機能が備わっているにも関わらずそのドキュメントがない場合、その機能を堂々と使うために、その機能の後方互換性を確保するために、その機能が作者の気まぐれで消滅してしまわないように、ドキュメンテーションのpull-requestを送っている。

なお、今回のDaikuの場合、ドキュメントのない機能があまりにも多かったので以下のようにして作業を進めた。

テストコードをひと通り見て、テストされている機能を洗い出す
テストされている機能を中心にドキュメントを書く
ドキュメントに書かれているがテストがない機能についてはテストを追加する

細かい話ではあるが、今回、Daiku::SuffixRuleモジュールにはあえてドキュメンテーションを行わなかった。これはなぜかというと、そもそも現状このクラスを直接使う必要がないといういことと、コミットログなどを見たところ今後機能拡張がされそうな気配を感じたからである。変化が見込まれるところに下手にドキュメントをつけると後でハマるので、それはそれで良くないと思う。