ドキュメントの場所を知らせるために、落ちるテストを作る

　今回はドキュメントの場所をどうやって気づかせるかという話を書く。

ドキュメントがあるときの問題

　以前開発のドキュメントをどこに置くか問題 - $shibayu36->blog;に書いたとおり、僕の意見としては

基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う
いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く
- 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う

というものだった。

　基本的には一番近いコメントにすると、見つけやすさ・更新しやすさともにある程度担保することが出来る。しかし、メインの部分が明確に決まらない*1いろんなパーツが関係しあう機能の場合は、ドキュメントを書かないと全体の概要が分からないということもある。このような時、ドキュメントを書いても結局そのドキュメントに気づかれないし、そのため更新されないという問題がある。

テストでドキュメントの位置を知らせる

　最近は一つの方法として、その周辺を触るときにほぼ必ず触るような部分の変更があったら、テストが落ちるようにしておいて、そこにドキュメントへのリンクを置くのはどうか、ということをしてみている。

　特定の機能へ何かしようとしたときにある設定の追加が必要だった場合を考える。ひとまず便宜上設定の仕様をドキュメントに書くのではなく、テストにしてしまう - $shibayu36->blog;にて使ったデータを使う。

[
   {
      "blog_url" : "http://shibayu36.hatenablog.com/",
      "permission" : "public",
      "can_be_edited_by" : [
         "shiba_yu36"
      ]
   },
   {
      "blog_url" : "http://shibayu36-private.hatenablog.com/",
      "permission" : "private",
      "can_be_edited_by" : [
         "shiba_yu36",
         "shiba_yu37"
      ]
   },
   {
      "blog_url" : "http://blog.example.com/",
      "permission" : "public",
      "can_be_edited_by" : [
         "example-user"
      ]
   }
]

　この時、設定を追加したら落ちるテストを用意しておいて、そこにドキュメントへのリンクを追加する。

subtest '設定の数が正しい' => sub {
    # この部分の機能を触る時は、まずdocuments/blog_config.mdを見ましょう
    is scalar @$blogs_config, 3;
};

　こうすると、以下の順序でドキュメントに気づいてもらえるんじゃないかと思った。

この機能のドキュメントを見たことなしに設定を追加した人は、CIサーバでこのテストが落ちてくれる
テスト修正しようとして、テストのファイルを見る
周辺にドキュメントのリンクがあるので、見てみる

　もちろんドキュメントはmarkdownで書いてなくてもよくて、メインに見て欲しいクラスへのリンクでも良いだろうし、なんでも良い気がする。

まとめ

　今回はドキュメントの位置をテストで知らせるという話を書いた。「メインの部分が明確に決まらない機能」というので、ブログに書いて良さそうな例が思いつかなくて、すごく分かりにくい説明になった気がする。

　実際にはこのような問題に当たったときに、ドキュメントに気づいてもらえればなんでもいいので、他にもいろいろ方法があると思う。なんかいい方法あったら教えて下さい。

$shibayu36->blog;

クラスター株式会社のソフトウェアエンジニアです。エンジニアリングや読書などについて書いています。

ドキュメントの場所を知らせるために、落ちるテストを作る

ドキュメントがあるときの問題

テストでドキュメントの位置を知らせる

まとめ

関連