Fe and Ni

戯言だよ

「要求を仕様化する技術 表現する技術」読書メモ - 第1部第2章 なぜ仕様のトラブルが起きるのか

それは「まともな要求仕様書」が書けていないからでは、という話。

ほんとこれな

仕様モレを見逃した本当の原因プロセスを改善しなければバグは発生し続ける

誰でもプロセスを「習慣」として身につけています。つまり、バグはその人の身につけている習慣(プロセス)がもたらしているのです。

一般に仕様モレは、いわゆる「不注意」でまとめてしまうことはできません。「注意」すれば防ぐことができるものではないのです。そこには、仕様書の構成などの「漏れる仕組み」や「発見できない仕組み」があるのです。

仕様FIXはうまくいかない

事前に要求仕様書のレビューを実施したにも関わらず、テストで発見されるバグのなかに仕様関係のバグが多く含まれていることは、そこにある要求仕様書はレビューでコメントが出せるものではなかったことを意味しています。

  • 抽象的な記述の要求仕様書にFIXの承認は本来できない
  • 「FIXしてくれないと実装が始められないので納期が遅れる」と言われて仕方なくFIXしているだけ
  • 結局後で仕様モレが発覚し、「この記述は当然こういう意味だと思った」「書いてないのだから仕様追加だ」などと揉めることになる

仕様化に必要な時間を投入していない/できないのは各行程の見積もり精度に根拠がないから

「コーディングが間に合わない」という不安に押しつぶされ、コーディング以外の作業はことごとく省かれるのです。

仕様書レビューで問題が検出できない

  • (要求)仕様書レビューで一番の障害はそこでの表現が「仕様」になっていないこと
  • 抽象的な表現が残っていて、その表現のなかにどこまでの動きを含んでいるのか見えないため、モレを指摘するにも迷ってしまう

・(ネット販売)購入の確認操作では誤操作が入る余地を排除してほしい
・部屋の様子を映したビデオは、インターネットを介して顧客のPCの画面から自在に操作して見られるように
・設定データが変更されたときは、あとで再現できるように必要な情報一緒に保存すること

  • 特に仕様書の一部ではなく全体に抽象的な記述がある場合、全てを指摘するのはレビューコストがかかりすぎるため、結局「全てスルー」することになってしまう恐れがある

レビュータイミングの問題

  • 最後にまとめてのレビューを設ける場合が多い
  • 基本的には一回のレビューしか想定されていない
  • ここでは多くの指摘がなされないことが前提になっている(仕様書に重大な欠陥があるケースを全く想定していない)

メモ

どんな問題が起きているのか?それは要求仕様書が原因か?

要求仕様書の書き方・構成が原因かもしれないトラブル

  • 仕様関係のバグが多い
  • 設計や実装の途中で仕様変更が多い(仕様不備を早期発見する仕組みが必要)
  • 途中で設計者のほうから仕様の問い合わせが多く発生している
  • テスト作業で仕様の確認が多く発生している(仕様書が「検証可能」な状態になっていない)
  • バグとして上がったが現状の動きに合わせて仕様のほうを変更した件数が少なくない(仕様間の絡みが判断できない状態)
  • 動いてからでないと何もコメントできない、と顧客や営業の人にいわれた
  • 根本的なアーキテクチャ上の設計ミスが起きている(仕様間の絡みが見えないか、アーキテクチャ上の配慮の必要性が見えない状態)

そんなときは

  • 暫定仕様がFIXしたときの対応を事前に考えておく
  • 仕様の変更件数・変更率を計測する
  • 問い合わせ件数と時期のデータで実態を把握
  • どのような表現・構成なら読まれるのか読み手の意見を聞く

バグデータx何かで見えてくるもの

  • 1000行あたりのバグ発生率 => プロジェクト全体の作業の品質の一面
  • 機能別バグ発生率(1000行あたりのバグ発生率を機能で分けたもの) => 発生率の低い機能における作業方法が問題解決の糸口になるかも
  • 機能別の仕様変更件数とバグ発生率との対比 => 仕様変更とバグに相関があるかどうか/仕様変更の少ない機能の仕様策定方法が参考になるかも

大事なことは、バグデータから自分たちの組織の問題を見つけるという姿勢を見せることです。

よくあるダメな要求仕様書

  • カテゴリには分けられているものの、「要求」が表現されていない
  • 「仕様」といわれているのに特定できない表現を含んでいる
  • 仕様なのか説明なのか分からない表現
  • ハードをコントロールするフローチャートが書かれていたりする
  • 品質要求が書かれていない
  • 「要求項目」「要件リスト」はあっても、仕様との対応させて扱っていない
  • 要件リストの分類と仕様書の分類が異なる

memo:
「要求仕様書に要求が表現されていないために、その機能にはどのような仕様が含まれるべきか、どこまでの範囲の仕様が含まれるべきかが見えない」っていうのは分かるんだけど、どう表現すればよいのか、が書いてあるのはまだ先…。

「要求」なのか「仕様」なのか、あるいは「説明」なのかを明確にして、その扱いを定義しておかないとつまらないところで仕様のトラブルを招いてしまいます。

memo: どんなトラブル?要求/仕様/説明の定義は後々出てくる?

画面仕様書の問題

よくある記載事項:

  • 画面遷移
  • 個々の画面の要素配置図
  • 表示域やボタンの簡単な説明

不足しているもの:

  • 表示域についての詳しい仕様
  • ボタンが押せない状況や、押したときの処理としてデータチェックやファイル保存、画面への反映などの仕様

それによって起きる問題の例:

  • 表示条件や状況によって表示領域の表示パターンを変えなければいけないことに実装段階で気づく
  • => 気づいた時点で対応する
  • => 新たな仕様トラブルの種を埋め込んでいる!(他の画面との整合性が崩れる/対応内容が仕様書にフィードバックされないので、後日思い出すにはソースコードを読まないと分からない、などが起きる)

仕様化に必要な時間を投入していない/できないのはなぜ?

  • そもそも仕様が明確になっていない状態での見積り工数には根拠がない
  • さらに、仕様を詰めずに実装してしまうと後々の仕様変更で元の何倍もの工数を失ってしまうことを分かっていながらも、仕様化の時間を事前に組み入れられない

なぜか?

「コーディングが間に合わない」という不安に押しつぶされ、コーディング以外の作業はことごとく省かれるのです。

何が問題?

  • 実装工数見積もりをしていない、または見積もりに自信が持つことができない
  • 開発プロセスが曖昧で、スケジュールの根拠が薄い

どうすれば?
見積もりをしていない => 見積もろう

見積もりに自信を持てない => 見積もりと実績を比較しよう

  • ソースコードサイズ・実装工数などの見積りと実績を比較
  • 比較結果を踏まえて見積もりを調整、精度を上げていく

レビューを実施しても後で問題が出てくるのはなぜ?

  • 要求仕様書のレビューでレビュアーが仕様モレや仕様間の衝突などの欠陥・問題を発見するには、構成や書き方が適切でなければいけない
  • 逆に適切な構成・書き方は、書き手にとっても仕様が漏れにくいもの
  • 「要求仕様書作成ガイドライン」を(できれば設計チームの人が)作成し、要求仕様書作成時にそれに従うようにすると構成が安定する

レビューしやすい要求仕様書のポイント

  • 設計や実装のイメージができるほどに具体的な表現であること(具体的)
  • 仕様の記述が発散しないように「範囲」の中でグループ化され整理されていること(分類と整理)

構成に問題がある

「概要」と「詳細」の問題

5章 計測機能
[概要](ここに、この計測機能についての動作や代表的な振る舞いが書かれています)
[詳細](ここから、計測の開始方法、測定データの集め方、集めたデータの表示方法などの仕様が書かれています)

  • [概要]内に[詳細]には書かれていない「仕様」が含まれていることがある
  • 上記を回避しようとすると[概要]と[詳細]で記載内容が重複せざるをえない(つまり、この構成は筋が悪い)

特に「概要」という文字のついた文書または「節」はレビューに耐えられません。内容は表面的で不完全ですし、書き手も「概要」ということでレビューに耐えるものを想定していません。そのような性質を持った「概要」のところに、見落とされては困るような「仕様」が書かれているとすれば、あまりにも無神経な行為といわざるを得ません。

memo: う、やってしまっているかも…。

無秩序な記述

仕様の括り方や設定情報と絡む仕様の書き方、エラーに関する記述の扱いなどが人によって違っていることがある
また、一つの機能の中でも記述順に秩序がないと漏れている仕様に気づきにくくなってしまう

インク切れ監視機能
・残りの印刷枚数が10ページ未満のときは、PCに通知しないで、印刷処理を続行する
・残りの印刷枚数が10ページを超えるときは、PC側に「危険」を通知する
・インク残量が「警報レベル」を示しているときは「警告」をPCに通知して新しい印刷の編集を停止する
・PC側から「続行」の指示を確認すればインク残量をチェックし、交換されたことを確認できたときは編集・印刷を再開する
・PC側から「中止」の指示が届いたときは、未編集のデータを廃棄する
・10ページ印刷ごとにインク残量を確認し、残りのページ数との間でインク切れの危険性を判断する

memo:
構成を直すとしたらどうなるんだろう…
仕様の中で気になったのは以下だけど、他にもあるかな?

  • 印刷開始時はインク残量確認する?
  • 「10ページ」のカウントはどうやる?ドキュメントをまたぐ?
  • インク残量のレベルは何段階?危険/警報はそれぞれどんな状態?
  • 「続行」「中止」の指示はいつ出るのか?危険通知のときも出る?
  • 「続行」指示後にインク交換が確認できなかったときは?
  • 指示の後に何かPC側に表示する?
  • PCに通知できなかったときはどうする?PCから応答がないときは?

レビューしにくい構成

  • 機能の動作・表示に影響する多くの"パラメータ"は「設定」というカテゴリで説明されていることが多いが、記述があちこちに点在しているとレビューの障害になる
  • エラーに関する記述も、機能ごとにまとめて書かれているケースと、それぞれの振る舞いの記述の箇所に配置されているケースがある(これはどちらも一長一短なので、両ケースが混在することが問題)

書き方に問題がある

「説明」か「仕様」か?

・予備バーナー点火ボタン
このボタンを押すと予備バーナーに点火する。予備バーナーは、タンクの温度があらかじめ定めた保温温度を下回ると自動的にメインバーナーの点火の種火ともなる。

  • 前半は予備バーナーの仕様
  • 予備バーナーの点火に条件はあるの?
  • 点火中に発生する異常状態に対する処理はどうすれば?
  • 後半はメインバーナーの仕様(メインバーナーはタンクの温度が下がると自動的に点火する。そのとき予備バーナーを種火とする)

仕様になりきっていない

要求仕様書レビューで一番の障害はそこでの表現が「仕様」になっていないこと
抽象的な表現が残っていて、その表現のなかにどこまでの動きを含んでいるのか見えないため、モレを指摘するにも迷ってしまう

・(ネット販売)購入の確認操作では誤操作が入る余地を排除してほしい
・部屋の様子を映したビデオは、インターネットを介して顧客のPCの画面から自在に操作して見られるように
・設定データが変更されたときは、あとで再現できるように必要な情報一緒に保存すること

特に仕様書の一部ではなく全体に抽象的な記述がある場合、全てを指摘するのはレビューコストがかかりすぎるため、結局「全てスルー」することになってしまう恐れがある

レビューのタイミングも問題

  • 最後にまとめてのレビューを設ける場合が多い
  • 基本的には一回のレビューしか想定されていない
  • ここでは多くの指摘がなされないことが前提になっている(仕様書に重大な欠陥があるケースを全く想定していない)

重大な欠陥の例:

  • 根本的に仕様がまとまって抜けている
  • エラーケースがほとんど書かれていない
  • 関連するパラメータに対する振る舞いがほんの一部しか書かれていない

レビューには2種類ある

  • 公式のレビュー:成果物の承認のためのレビュー
  • 半公式のレビュー:成果物の欠陥を発見するためのレビュー

半公式の「逐次レビュー」がおすすめ/例えば以下のタイミングで実施

  • 要求仕様書の全体構成を考えたとき
  • 一つの主要機能の仕様構成イメージが固まったとき
  • 一つの主要機能の仕様が書かれたとき

逐次レビューの危険

前回のレビュー範囲では問題なかったが、今回のレビュー範囲の中で以前に確認された仕様と矛盾するところが出てくる可能性がある
=>
レビュー範囲を「今回仕様化された範囲」に限定せず、「機能間の関連マトリクス」などを参考にしながら仕様の矛盾に気づく機会をつくる

仕様書を書くことに対する誤解

  • 仕様間の絡みを解決し、きちんと「整理がついた状態」を表現するものと考えている
  • 頭の中で絡み合う仕様をほぐしてから「完成した姿」を書こうとしている
  • 依頼者から渡された「要求仕様書」に対して、設計者の方で不足している仕様を"補充する"という発想がなく、作業枠が確保されていない

「仕様化」は「決めていく」作業

  • 順番に仕様として「決めて」いき、仕様の衝突や絡みが出てきたら戻って調整すればOK
  • 仕様書がない場合、コーディングしながら「仕様を決めて」いるはず
  • ただ、コーディングと仕様化を同時にやると次第に混乱してきてしまう(問い合わせに日数がかかったり、「戻って調整」するのが3週間後でもう記憶にない…などの問題が起きるため)