未来のいつか/hyoshiokの日記

hyoshiokの日々思うことをあれやこれや

無駄なドキュメントは書くな（再考）＠大井町の飲み屋談義

昔、無駄なドキュメントは書くな(http://d.hatena.ne.jp/hyoshiok/20050510#p1)というよた話を書いたのだが、酒の席で、似たようなお話をしたので、いろいろ考えてみた。

酒の席でのお話というのは、次の日すっきり、さっぱり忘れるのが常であるので、詳細はもちろん把握していないのだが、概要程度は思い出せるので、それを再現してみたい。

登場人物は、工程改善チームのおじさんTさん、工程改善チームの若者（初対面）、SIerから転職してきた同じグループで9月入社のSさん、そしてわたくし。大井町の魔界のおでん屋の2階。民家の2階風で、テレビもある。だらだら終電までいればタモリ倶楽部も見られるねと言う感じの飲み屋である。

若者はドキュメントの標準化とかいろいろ悩んでいる。若者「詳細設計ドキュメントとかどうするんすかね？どー標準化するんすかね」、よしおか「そんなものは書かない」、若者「書かないんすか」、よしおか「書かない。書く意味がわからない」、Tさん（工程改善チームのおじさん）、若者に向かって「ね、このおじさん（わたしのこと）、おもしろいこと言うでしょ」

というようなラブリーな会話が大井町の飲み屋で繰り広げられたのである。

SIer出身のSさんには、日頃、わたしが同じグループということもあり、「それってウォーターフォールの匂いがしますね」とか、「テスト書かないなんてプロじゃないっすよ」とか、好き勝手なことを申し上げているので、だんだんわたしの芸風が分かって来たようである。

それはともかく、必要なドキュメントは、そのシステムのWHYを書いたドキュメントである。なんで、そのシステム、あるいはサービスを作ったのか、その魂を記したドキュメントである。こーゆーことをやりたい。こーゆーことを解決したい。これで、お金をがっぽがっぽ儲けたい。なんでもいいが、ともかく、これをなんで作ったのか、何を解決したいのかということを明確に過不足なく記したドキュメントである。要求仕様書に書き込む。

それを元に外部仕様書を作る。この要求には、こーゆー風に応えるみたいな。APIなんかもきっちり記す。

詳細な実装についてのドキュメントは無駄だから書かない。それはコードに書いてある。動作については、テストがある。

レガシーコードを再構築するプロジェクトなんかがよくある。WHYを記したドキュメントがない。テストもない。詳細ドキュメントもない。コードしかない。というようなプロジェクトである。

担当者がコードを読みながらせっせとHOWの部分を再構築したりする。大変な時間と労力をかけて詳細ドキュメントを作る。そーゆープロセスがまかり通っていたりするが、そんな時間があるんだったら、テストを書こうよ。メンテされないドキュメントを書く時間があったらテストを書こうよ。テストを作った方が、気持ちいいし、楽だし、後々の工数を激減するし、何よりもいいリズムを生むよ。

テストを作ることは気持ちのいいことなんだということをプロジェクトに導入する。テストを作らないことは気持ちが悪くて、先に進めない。そーゆー空気を醸し出すことが重要なのだ。

変更の履歴は、ソースコード管理システムががっつりフォローしてくれる。だからSubversionとかgitを使うのである。Changelog的なドキュメントは重要である。ちゃんとログを書くというのも、書かないと気持ち悪いからで、プロだったらちゃんと書く。それがリズムだし、気持ちいいし。

大規模システムになると、WHYの情報がどんどん失われてくる。そもそもそのようなドキュメントがない。その場合は担当者にヒアリングして、それを再構築する。当初の魂を発見する旅に出る。担当者が退職していなくなってしまったりするが、当時の事情を知る人々から様々な視点での思いを語ってもらう。それは時間がかかるが重要な仕事である。ここをはしょると似た姿を持った当初の狙いとは似ても似つかないモンスターを作ることになる。

原点に立ち戻って考えてみる。

レガシーシステムのデザインリカバリーというのは、そーゆー作業だと思う。

無駄なドキュメントは書かない。

というようなことを、工程改善チームの若者に大井町の場末の飲み屋で熱く語ったのである。

読者に向けての注意

上にあげた例は、Webサービスなどの構築などを想定していて、外部SIerへ発注するエンタープライズシステム、基幹システムなどの構築とは微妙にコンテキストが異なる。Webサービスを自社開発し保守運用するイメージを想定してほしい。

さらに余談。下記には詳細設計書（これを誰かに渡せばコードを書いてくれるようなもの）を書くべきか否かという話題についての微笑ましい議論がある。10年以上前のお話である。若き日のまつもとさんも参戦している。
http://groups.google.co.jp/group/fj.comp.oops/browse_thread/thread/1679653cb0273548/79ce9b384a66d821?hl=ja&pli=1