IT古典良書を読み解く《第3回》やさしい機能仕様 前編
第3回 Joel on Software(ジョエル オン ソフトウェア) －その3－「やさしい機能仕様 前編」
エンジニアとドキュメント
こんにちは。スクラムマスターの伊藤です。
「ドキュメントを作成するのは好きですか？」と、プログラマに質問すると、かなりの確率で「いいえ」と回答されるでしょう。「はい」と答えたプログラマがいたら、その人が書いたコードをチェックして、しかるべき仕事をしてもらったほうがいいかも知れません。（まぁ、日本では書き過ぎて好きなる人もいますが）
はい。今回は仕様書の話です。
ジョエルテストの「7. 仕様書はある？」にはジョエルの元にも非難轟々だったそうです。それほど、エンジニアはドキュメントを作成することが嫌いなのです。そして、作成しない理由は「仕様書作成フェーズをとばして時間を節約しているんだ」です。しかしながら、ジョエルは仕様書を作成しないことは最大かつ不必要なリスクと言っています。
なぜ、エンジニアは仕様書を作成することが嫌いで、作成しないことで、どんな悲劇があり、作成するポイントは何かを紐解いていきましょう。
引用: Joel on Software
51ページ「第5章 やさしい機能仕様 パート1：なぜわざわざ書く必要があるのか」
59ページ「第６章 やさしい機能仕様 パート2：仕様書とはどんなものか」
73ページ「第７章 やさしい機能仕様 パート3：だけど……どうやって書くの？」
79ページ「第８章 やさしい機能仕様 パート4：ヒント」
(原文)
- Painless Functional Specifications – Part 1: Why Bother?
- Sample https://www.joelonsoftware.com/whattimeisit/
- Painless Functional Specifications – Part 2: What’s a Spec?
- Painless Functional Specifications – Part 3: But… How?
- Painless Functional Specifications – Part 4: Tips
(日本語アーカイブ)
(４章に渡る長編。おっと、なぜか、この章は一部しか日本語訳アーカイブが無いぞ。前後が無いと意味不明なところがあるが、賢明なる読者は既に本を入手しているか、英語がスラスラ読めるはずなので、このまま進めてみます。)
- Sample https://bit.ly/2zWg2Xw
- やさしい機能仕様 パート4：ヒント https://bit.ly/3ea1IcB
《よもやま話》
一昔前は、ソフトウェアとドキュメントの電子版を入れたCD-Rとドキュメントを印刷したキングファイルでした。何故か、ドキュメントの厚みがある方が良いという風潮がありました。受領した方もキャビネットの肥やしにしかならなそうですが…
印刷作業が大変なのは言うまでもないですが、おかげさまでマクロの技術が大幅に向上しました。ちなみに、筆者が見積もり等を作成するときは、納品物の欄で、ドキュメントは電子版だけでよいかを確認し、無駄な作業は初めから取り除くよう心がけていました。
良いドキュメントと悪いドキュメント
エンジニアがドキュメントを書かない理由について、ジョエルは以下のようにあげています。
1. 時間節約のため
これは日本でも、よく行われます。ドキュメントが無くてもソフトウェアは動くため、時間がない場合は、飛ばしたり後回しにしたりすることがあります。
2. 誰も読まないため
はい。そうですね。キャビネットの肥やしになったりします。ジョエルは「仕様書が出来上がると、棚に収められ、再び取り出されることはなく、製品は仕様書に書かれていることとは無関係にスクラッチから実装される」と書いています。
3. アサリ蒸し器
アサリ蒸し器って何だよ！と突っ込まれそうですが、アメリカン・ジョークでしょうね。これが日本でも1番の理由だと思います。ここは、そのまま引用しましょう。
誰か（多くは顧客）が言う。
「おい、ちょっと！ 君はアサリ蒸し器が付いているといったはずだ！ アサリ蒸し器はいったいどこにあるんだ？」
それに対してプログラマは答える。
「それは違います。仕様書の第3章、4節、パラグラフ2.3.0.1を見ていただければ、『アサリ蒸し器は付いていない』とはっきり書いてあります。」
しかし、これでは顧客は納得しない。顧客はいつでも正しいので、不平たらたらのプログラマはアサリ蒸し器を後から追加しなければならなくなる（そして彼らはますます仕様書について懐疑的になる）。
はい。そうですね、心当たりがありすぎて、胸が痛いですね。しかも、このアサリ蒸し器はリリース後使われることは無かったりするんですよね。一部から、ちゃんと仕様書凍結の承認を得ればいいじゃないかという声が聞こえそうですが、仕様書に明記され、承認したはずでも（どうせ読んでない）、いくら現場が突っぱねても、今回は特別にと営業や、偉い人に根回しされ、最後は業務命令という形でアサリ蒸し器を追加するハメになるのです。もちろん、納期は変わりません。プロジェクト終了後に人が減るのは当然のことでした。
4. プログラム設計書の怪
ちなみにジョエルが仕様書として言っているのは機能仕様書であって技術仕様書ではないとうたっています。技術仕様書について作成有無は言及がないので、作らなくていいか必要に応じて作成すればいいというレベルだと思われます。
プログラム設計書を作成してくださいと言われた人もいるでしょう。筆者も最初、それは何ですかと聞きましたが、どうプログラミングするかを書いてあるドキュメントだそうです。具体的には関数名だったり引数、戻り値、クラスだったりが書いてあったりするのですが、デバッグもせずに机上でそんなもの書ける人がいたら、バグは存在しないだろうと思います。
実際のところは完成したコードを元にプログラミング設計書を書くということが行われます。仮に先に作っても、絶対にその通りにはならないので、手戻りが発生するためそれならばコードを元に後で作ろうという本末転倒（というかこの仕様書いる？）なことが発生します。
この悩みも万国共通なのか、頭の良い人がJavadocのようなコードから仕様書を作成してくれる各種ツールが登場しました。コメントをフォーマット通りに書くと更に素敵なことに。ちなみにプログラム設計書が必要な理由は「納品物に含まれている」からです。それだけです。後の拡張時に別のプログラマが理解を早めるためにはあってもいいでしょうが、それであればツールで作成すれば十分なのと、綺麗なコードと本当のコメント（コピペの功罪なのか嘘コメントは結構存在します）を残してくれると助かります。
ここまでみて、良いドキュメントの条件がみえてきました。読んでもらえる機能仕様書であることです。そして、悪いドキュメントは読まれないドキュメント、無駄な技術仕様書です。納品物に無駄な技術仕様書が含まれている場合は、ツールで作成して納品すれば何も言われない（ほとんど読まれることは無い）。敵は内部にいることもあります。UMLが大好きで全てのUMLを作成するように指示する（なんと13種類もある。）PMにあったってしまった場合は、こちらへ。
仕様書作成のメリットと悲劇
では、良いドキュメントを書くメリットとはなんでしょうか。ジョエルは以下の３つを挙げています。
1. 仕様書を修正するのは数分だがコードを修正するには数週間かかる
これはイメージしやすいと思いますが、仕様書の時点で誤りに気付けば修正は容易ですが、プログラミング後に誤りが発覚すると、修正は大変です。しかも、プログラマは自身でコードを書くとどんなにまずいコードであっても、そのコードに執着するようになります。
ここで起こる悲劇は、そのまずいコードを何とか活用して製品を完成させようという間違った努力をせざる得なくなってしまうことです。
2. コミュニケーションにかかる時間を節約できる
仕様書があることで、チームのみんなは仕様書を読めば、仕様を理解できる。これにより、品質保証の人たちは、何をテストすればいいのか理解する（仕様書が無い中、何とかテストケースを作成しているQAチームの皆様 本当にお疲れ様です。いつも、ありがとうございます。）
マーケティングの人たちはWebに載せるものを書くために仕様書を使う。開発者たちはどういうコードを書くべきかを知るため仕様書を読む。顧客は自分の欲しい製品であることを確認するために仕様書を読む。テクニカルライターはマニュアルを作成するために仕様書を読む。マネージャーは経営会議で何が起こっているのか知っているような顔をするために仕様書を読む。
などなど。。。
ここで起こる悲劇はテクニカルライターの例が面白いと思います。（日本だとほとんどいないポジションですが）
たとえば、画面に次のようなメッセージが出る。
LRF-1914サポートを有効にしますか？
それであなたが「ヘルプ」をクリックすると、悲喜劇的なヘルプトピックが現われて、次のようなことを言ってきます。
LRF-1914サポートを有効（デフォルト）にするか無効にするかを選択します。LRF-1914サポートが必要なら[Yes]をクリックするか[Y]を入力してください。LRF-1914サポートが必要ないなら、[No]をクリックするか[N]を入力してください。
LRF-1914サポートが何か知らないという事実をどうにか隠そうとしているのは明らかですね。彼らがプログラマに聞くことができなかったのは、企業の病理がいくつも重なったののですが、根本的な理由は仕様書がないということ。
そして、我々は遂になぜヘルプがあんなに使えないのかの理由をここで知る由となりました。
3. スケジュールが立てられる
日本企業はほとんどが受託案件のためスケジュールの納期だけは決まっていることが多いです。それとは別に、ソフトウェアの開発では決めなくてはいけないことが多いですよね。そして、議論で誰も結論を出そうとせず（アメリカ人がこう書くんですからね…）、時間がたつと難しい決断がすべて最後に残されることになります。
そういうプロジェクトはほとんど間違いなく迎える失敗。
仕様書を書くというのは、こうした苛立たしいデザイン（仕様）上の判断（仕様書がないと隠されてしまいがちな大小の判断）を明確にする優れた手法なのです。
だけど…どうやって書くの？
仕様書の必要性、書かないことのデメリット、書くべき仕様書（機能仕様書）についても、分かりました。じゃあ、書きましょうといっても書けないのが人間です。
うーん、大分長くなってしまいましたね。サブタイトルに前編と付いていることに気付いたあなた。流石です。というわけで後編に続きます。
――――――――――――――――――――――――――――――――――
執筆者プロフィール：伊藤慶紀
大手SIerにて業務用アプリケーションの開発に従事。
ウォーターフォールは何故炎上するのか疑問を感じ、アジャイルに目覚め、
一時期、休職してアメリカに語学留学。
Facebookの勢いを目の当たりにしたのち、帰国後、クラウド関連のサービス・プロダクト企画・立ち上げを行う。
その後、ベンチャーに転職し、個人向けアプリ・WebサービスのPM、社内システム刷新など様々なプロジェクト経験を経てSHIFTに入社。
趣味は将棋、ドライブ、ラーメン、読書など
お問合せはお気軽に
https://service.shiftinc.jp/contact/
SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/
SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/
SHIFTの導入事例
https://service.shiftinc.jp/case/
お役立ち資料はこちら
https://service.shiftinc.jp/resources/
SHIFTの採用情報はこちら
https://recruit.shiftinc.jp/career/