なぜドキュメントを書かない？

久しぶりに『ジョエル・オン・ソフトウェア』を読んだ。Amazon で調べたら、最近、この本の続編である『モア・ジョエル・オン・ソフトウェア』が出たようだ。

ジョエル・オン・ソフトウェアの著者である Joel Spolsky はソフトウェア業界での豊かな経験を持つ開発者で、彼のウェブログ "Joel on Software" はプログラマ向けサイトとしては最も人気のあるものの一つで、彼はマイクロソフトの開発者だったころ Microsoft Excel 等多くの有名なソフトウェア製品の開発に携わった。

彼がブログで記事にしたことをまとめた最初の本が『ジョエル・オン・ソフトウェア』である。もともとはブログの記事であり。アメリカ人でないとわからないようなスラングや引用（例えばジョージ・ブッシュ大統領の口癖 Not gonna do it! 「それをやるつもりはない」等）がふんだんにちりばめられており、読みにくいと言えば読みにくいが、ところどころで「まさにその通り！」と膝を打ちたくなる部分がある。

まずは、『第5章 パート1：なぜわざわざ書く必要があるのか？　やさしい機能仕様』の一節を読んで欲しい。

【ジョエル・オン・ソフトウェア　第5章 パート1：なぜわざわざ書く必要があるのか？　やさしい機能仕様　より引用】

　私の考えでは、ちっぽけではないあらゆるプロジェクト（1週間以上のコーディング、あるいは2人以上のプログラマを要するようなもの）において、仕様書がなければ常に、より多くの時間を費やし、より品質の低いコードを作ることになる。理由はこうだ。

　仕様書の最も重要な役割はプログラムをデザインすることだ。たとえあなたがすべてのコードを1人で書いているのだとしても、純粋に自分自身のためだけに仕様書を書くのだとしても、仕様書を書くという行為自体によって－プログラムがどう機能するか詳細に記述することによって－プログラムを実際にデザインするように強いられるのだ。

－中略－

人間の言葉で製品をデザインしているときは、いろいろな可能性について考え、修正し、デザインを改良するのに数分しかかからないということだ。ワープロ文書の段落を1つ削除するのを残念に思う人はいない。しかし、あなたがプログラミング言語で製品をデザインしているなら、反復デザインには何週間もかかる。さらに悪いことにあるコードを書くのにほんの2週間かけただけで、プログラマは、どんなにまずいコードであっても、そのコードにとても執着するようになる。たとえそれが最高のアーキテクチャを表現していなくても、上司や顧客が何と言おうとも、スピーディにその美しいコンバータのコードを捨てさせるこてはできない。その結果、最終的な製品は、初期の間違ったデザインと理想的なデザインとの間の妥協の産物になりがちだ。それは、「すでに書いてしまったコードがあり、そのコードは捨てたくなかったので、それを前提とすれば私たちに得られた最良のデザイン」ということになるのだ。これは「私たちに得られた最良のデザイン」ほど良いものではないのだ。

　これが仕様書を書く大きな理由の1番目だ。大きな理由の2番目はコミュニケーションにかかる時間を節約できるということだ。あなたが仕様書を書いておけば、プログラムがどう動くと想定されているか一度だけ説明すれば済む。チームのみんなはただ仕様書を読めばいいからだ。品質保証の人たちは、プログラムがどう動くを想定されてるか知るために仕様書を読み、何をテストすればよいのかを理解する。

－中略－

　このコミュケーションは不可欠であり、あなたが仕様書を書いていない場合でも発生するが、その場合は行き当たりばったりに発生することになる。品質保証の人たちがしだいにあれこれとプログラムをいじり回し、そして何か奇妙なことが起きるたびにプログラマを邪魔して、どうなるのが正しいのかについてばかげた質問をする。これがプログラマの生産性を損なうという問題は脇に置いておくとしても、プログラマというのは「正しい答え」ではなく彼らがコードをして書いたことに即して質問に答える傾向がある。だから、品質保証の人たちは仕様に従っているかをテストするのではなく、プログラムの挙動に沿ってそのプログラムをテストすることになってしまうわけで、これは、なんというか、もう少しマシにやれたはずなのだ。

【引用終わり】

機能仕様書を含むソフトウェアドキュメントを書くことがムダである、役に立たない、その時間をプログラミングやデバッグに費やした方がマシだという声を間接的に聞くことがある。間接的にというのは、面と向かっては言わないが品質保証担当がいないときに、開発が遅れていることの理由としてやり場のない怒りに対して、要求されるドキュメントが多いということが開発が遅れる原因だとプロジェクトの内部で愚痴っているのだ。

自分がプロジェクトの遅れの原因にされているソフトウェアドキュメントだったら「それは、濡れ衣だ！」「 プロジェクトの遅れはドキュメントのせいじゃない！」と叫んでいるだろう。ドキュメントはしゃべれないから口をきけない者に問題の原因を押しつけているだけだ。ひどい話だ。

そう思っていたら、『ジョエル・オン・ソフトウェア』に上記のようなことが書いてあった。

ドキュメンテーションという行為はソフトウェアの設計に他ならない。いきなりプログラムを書き始めるのはもっともレベルの低い設計であり、自然言語や図表を使ってソフトウェアドキュメントを作るということがレベルの高い（抽象度の高い）設計行為だ。 Joel Spolsky が語っているドキュメントが必要な一つ目の理由が「ドキュメンテーションはプログラムをデザインすること」なのだが、2つ目の理由であるドキュメントがあることによって各部門とのコミュニケーションを効率的に行えると言う点は同意するものの、日本のソフトウェアプロジェクトでは難しい面があると感じる。

日本の小規模な組込みソフトウェアプロジェクトでは、プログラマが仕様も作成し、マーケティングもテストも品質保証もしなければいけないことが少なくない。品質保証という名が付く担当部門があってそこに担当者がいても実施的なソフトウェアの品質保証作業はプログラマがやっていることもある。

だれからも読まれないドキュメントを作るのは確かに辛い。誰かが読んでくれるから、自分や他の誰かのために役立つからドキュメントを書こうという気になる。

だから自分はレビューがあるときは事前に全部のドキュメントに目を通す。斜め読みするのは得意なので、数十ページのドキュメントでも10分くらいあれば問題点や「よく見てるね」と言われるような質問項目をピックアップすることができる。だから、レビューの数時間前に書類が送られてきてもへっちゃらだ。

的確に問題点や良い点を見つけてレビューで伝え、こういうときには何をチェックする必要があるのかをレクチャーする。時間かけて作ったドキュメントを読んで評価してくれる人がいれば次のドキュメンテーションの動機につながる。日本のソフトウェアプロジェクトがドキュメントを書かない理由のひとつに「誰も読んでくれない」ということがあると思う。

『あるコードを書くのにほんの2週間かけただけで、プログラマは、どんなにまずいコードであっても、そのコードにとても執着するようになる。最終的な製品は、初期の間違ったデザインと理想的なデザインとの間の妥協の産物になりがちだ。』という Joel Spolsky の主張はその通りだと思う。

これは個人的な感覚だが、自分はプログラムを書き直してプログラムがきれいになる、アーキテクチャが美しくなるのなら、今のコードを捨てることにぜんぜんためらいがない。（もちろん心に余裕だないとダメだけれど） 自分が作ったコードにきったないところがあって、後で誰かから「あれはないだろ」と言われるのは我慢がならないし、陰でクスクス笑われるのも嫌だ。やはり「いい仕事しているね」と言われたい。

だから、いつも自分がアウトプットした成果物をできるだけ第三者の客観的な目になったつもりで批評し、指摘されそうな部分があったらためらいなく直す。これを繰り返していると「ひとりピアレビュー（セルフレビュー）」ができるようになる。熟練すると質問されそうなことをいくつも想定できるようになるので、成果物をレビューされるときもスムーズな回答ができる。

ひとりピアレビューができるようになるのはそう簡単ではないので、やはりプログラマやソフトウェアエンジニアがモチベーション高く仕事を続けるためには、彼らの仕事を誰かがきちんと見て評価してあげないといけないと思う。成果物をほったらかしにせず、少なくともプログラムを作ったプログラマ以外の誰かが評価してあげることが、ドキュメントの必要性を理解させ、ドキュメントが役に立つことを体感させることにつながると思う。

P.S.

最近、昔作ったソフトウェアのことを聞かれ、10年前の日付が入っているドキュメントとソースコードを提供して再利用されたことがあった。ソースコードではなく、そのソフトウェアの元となる考え方自体が有用だったこともある。3年以上前に作ったソフトウェアだと自然言語で書いたドキュメントやモデルなどがあるととても助かる。こういうことがあると、あの時ドキュメントを作ったり、作らせたりして、キッチリいい仕事しておいて良かったと感じる。