『Joel on Software』 仕様書とはどんなものか?

 

Joel on Software

Joel on Software

 

 

ジョエル・スポルスキ - Wikipedia

Stack OverflowやTrelloを生み出したFog Creek Softwareの創立者

仕様書を書くことの必要性について、書かれているのでまとめた。

 

パート1:なぜわざわざ書く必要があるのか

何よりも仕様書を書かないというのは、あなたがソフトウェアプロジェクトに持ち込む、最大かつ不必要なリスクなのだ。それは着替えだけリュックに詰めて、その場になればなんとかなるさとモハーベ砂漠の横断に出発するのと同じくらい愚かなことだ。

仕様書がなければ常により多くの時間を費やし、より品質の低いコードを作ることになる。

1.  仕様書の最も重要な役割

プログラムをデザインすること。仕様書を書いてプログラムをデザインすることで、いろいろな可能性について考え、修正する。仕様書を作ることで、顧客との認識の違いを改めることができる。さらに上司や別の人のアーキテクチャについて意見を聞くこともできる。多くのプログラマは優れた設計でなくても自分が書いたコードを捨てたがらない。

2. コミュニケーションにかかる時間を節約できる

仕様書を書けばプログラムがどう動くのか一度だけ説明すれば済む。顧客・プログラマー・テスター・マーケティングなどソフトウェアに関わるステークホルダーは仕様書を読むだけで良い。

このコミュニケーションは不可欠であり、あなたが仕様書を書いていない場合でも発生するが、その場合は行きあたりばったりに発生することになる。

テストを書くときも仕様に従っているかテストするのではなく、プログラムの挙動に沿ってプログラムをテストすることになってしまう。

3. 詳細な仕様書がないとスケジュールが立てられない。

よく一般的に見られる誤りは何をどう作るべきかについて決めないこと。仕様書がないのでプログラマはさしあたりのない、部分から作り始める。そういうプロジェクトはほとんど間違いなく失敗する。

 

パート2:仕様書とはどんなものか

機能仕様=ユーザの観点から製品がどのように動くかを記述する。プログラムがどのように実装されるかは問題にしない。ここで話題とするのは機能であり、画面とか、メニューとか、ダイアログとかいったものの仕様を定める。

 

技術仕様書には、プログラムの内部の実装について記述する。ここで話題とするのは、データ構造、リレーショナルデータベースモデル、プログラミング言語や開発ツールの選択、アルゴリズムといったものである。

1. 仕様書は一人で書かれ責任と所有権を持つべき。

グループで仕様書を書いた場合、無駄な作業が発生する。仕様書におかしい部分があればその仕様書の責任者に修正する責任がある。

2. 詳細。機能仕様書で最も重要な部分。

すべてのエラーケースに言及するくらい詳細に立ち入って記述する。誰かがくださなければならない決定について記述する。

ex. パスワードが間違っている場合、メールアドレスが正しくない場合。

仕様書には決定を記述する必要がある。

3. 未解決の問題

仕様書の最初のバージョンで決まっていないことがあっても問題ない。しかし、コードを書く段階では全て片付いて置かなければならない。結局、未解決の問題が後にコードの設計や実装に影響を与えうる。

4.仕様書は生きている必要がある

仕様書は常にアップデートされている必要がある。その製品がどう機能するかについて仕様書に書かれている。仕様書の変更した箇所にリビジョンマークを付けておき、他の人がすべてを読み直さなくて済むようにしておく。

 

パート3:だけど・・・どうやって書くの?

誰が仕様書を書くべきかについて。大規模な会社についての話だと思うので割愛。

 

パート4:ヒント

仕様書を誰も読まないのであれば意味がない。プログラマは仕様書を緻密な学術論文みたいに書く傾向にある。「正しい」仕様書=難しいではない。読む人が理解しやすい仕様書を、できる限りわかり易く書く必要がある。一枚の画像は千の言葉に勝る。

 


現在のプロジェクトは悲しいことにめちゃくちゃで仕様書が存在しない。顧客の要望に対して断るという選択肢がなく、突貫工事的にどんどん機能を追加していくという有様で、なぜこんなことになるのかといつも考えていた。そもそも機能がどう動くのか正しいのかわからない・よしなにこう動けばいいと想像しながら実装する・そして顧客から認識が違うと言われ、修正するみたいなことを繰り返している。結果として、カラムが突発的に追加されデータベースはめちゃくちゃ、プログラムも色んな所にロジックが散らばっている。

『Joel on Software』を読んで、仕様書がないことがいかに問題か、そして現在のプロジェクトの問題の根源を知ることができたと思う。まず、仕様書は機能がどのように動くのかを説明する。これによって顧客との認識のズレを埋めることができる。またより良いアーキテクチャについて他者から意見を聞くことができ、工数の見積もりもより正確になるだろう。全くそのとおりだ。機能のあるべき姿を知らなければ、どのように実装するのかもわからないし、どこを変更すればいいのかもわからない。仕様書の第一義的責任は誰が持つのか?それは仕様書を作成したものであるべきだ。仕様書を作成した人がその機能がどう動くのか説明するべきである。そして仕様書は常に更新しておかなければならない。そうしなければもはや誰も全体を把握することはできなくなるだろう。この機能はどう動くべきなのだろう?作ったプログラマに聞くしかない。