$shibayu36->blog;読者になる$shibayu36->blog;株式会社アンドパッドでエンジニアをしています。プログラミングや読書のことなどについて書いています。2014-04-13ドキュメントの場所を知らせるために、落ちるテストを作る今回はドキュメントの場所をどうやって気づかせるかという話を書く。$shibayu36->blog;に書いたとおり、僕の意見としては基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思ういろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く出来るだけrepository内に入れておくと探しやすく、更新しやすいと思うというものだった。基本的には一番近いコメントにすると、見つけやすさ・更新しやすさともにある程度担保することが出来る。メインの部分が明確に決まらない*1いろんなパーツが関係しあう機能の場合は、ドキュメントを書かないと全体の概要が分からないということもある。このような時、ドキュメントを書いても結局そのドキュメントに気づかれないし、そのため更新されないという問題がある。テストでドキュメントの位置を知らせる最近は一つの方法として、その周辺を触るときにほぼ必ず触るような部分の変更があったら、テストが落ちるようにしておいて、そこにドキュメントへのリンクを置くのはどうか、ということをしてみている。特定の機能へ何かしようとしたときにある設定の追加が必要だった場合を考える。$shibayu36->blog;にて使ったデータを使う。}]この時、設定を追加したら落ちるテストを用意しておいて、そこにドキュメントへのリンクを追加する。3;};こうすると、以下の順序でドキュメントに気づいてもらえるんじゃないかと思った。この機能のドキュメントを見たことなしに設定を追加した人は、CIサーバでこのテストが落ちてくれるテスト修正しようとして、テストのファイルを見る周辺にドキュメントのリンクがあるので、見てみるもちろんドキュメントはmarkdownで書いてなくてもよくて、メインに見て欲しいクラスへのリンクでも良いだろうし、なんでも良い気がする。まとめ今回はドキュメントの位置をテストで知らせるという話を書いた。「メインの部分が明確に決まらない機能」というので、ブログに書いて良さそうな例が思いつかなくて、すごく分かりにくい説明になった気がする。実際にはこのような問題に当たったときに、ドキュメントに気づいてもらえればなんでもいいので、他にもいろいろ方法があると思う。なんかいい方法あったら教えて下さい。2リンクプライバシーポリシーはてなブログをはじめよう!shiba_yu36さんは、はてなブログを使っています。ブログを報告する引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。