この記事はなに?

私は就業以来、組込みソフトウェア開発をしてきました。
要求仕様の理解に時間がかかったり、要求仕様を誤って解釈し検証してしまったために作業の出戻りが発生したり・・・と失敗をしてきました。
この記事では【要求仕様を正しく理解する】ために気をつけることを共有させてください。

背景・目的

自社向けの勉強会でなにかテーマを決めて、ソフトウェア開発の上流工程から下流工程まで説明する連続講座を開催し、自分のスキルアップしたいと考えました。
講座参加者に学びになれば尚良、と考えました。

現在予定している講座はつぎのとおりです。

要求仕様の理解　★いまここ
要求仕様の定義・仕様化
設計
テスト
実装

今回の講座の資料はこちらにアップロードしました。

テーマ

テーマは 【既存組込み製品のマイコンを移植する】 にします。

対象装置はCQ EVカート
私が持っておりドメイン知識がある。
ソフトウェアの構造を理解している。
対象装置のマイコンが生産中止になった ⇛ 学習・スキルアップのために別マイコンに移植してみよう!!!

※今回はテーマに依存した内容は書きません。

用語の定義

まずは用語の定義をします。
みなさんは

要求仕様
仕様

をどのような位置づけで認識していますか?
今回は次の定義にしたいと思います。

要求仕様：装置・システムが実現したい目的
仕様：要求仕様を実現するための具体的手段

要求仕様は「〜したい」など要求を示す言葉で表現します。

要求仕様を正しく理解しないために起きる弊害

要求仕様を正しく理解しないことで起きる弊害を考えてみました。

要求仕様を理解するために時間がかかり工数増加
要求仕様の解釈を間違えたことに気づき作業が出戻る
要求仕様定義側-要求仕様読み手の関係性悪化で品質の低下

1は要求仕様書の記載がわかりにくいために読むのに時間がかかるということです。
2は要求仕様書の記載が複数の解釈を読み手に与えてしまうことが原因と考えられます。
3は要求仕様定義側の「こうしてほしいと思っていた」と要求仕様読み手側の「こういうことだと思っていた」の認識ズレが多く発生すると人間関係の悪化、ソフトウェアの品質低下にもつながる可能性があると思いました。

こんな要求仕様書の記載は嫌だ

要求仕様の理解で苦しんだ現象・考えられる解決案を書きます。
次に挙げた内容に気をつける・もし同様の内容に遭遇したら改善活動をするなどプラスに捉えてもらえれば・・・と考えています。

要求仕様の重複記載

現象

要求仕様の記載が複数の仕様書に重複して記載されている。つぎの特徴がある。

仕様書のメンテ忘れにより要求仕様に矛盾が生じる。
複数仕様書のメンテが大変。

解決策

要求仕様は重複しないように記載する。
⇛ DRY原則と同じですね。

要求仕様書が複数にならないように仕様書の構成から検討したほうがよさそう。

ドメイン知識の属人化

現象

対象ソフトウェアのドメイン知識・要求仕様がチームに共有されておらず、特定の人の頭の中にしかない。

解決策

属人化している理由(※)を明確にした後、特定の人のドメイン知識を共有する場を設ける。
※特定の人が業務過多であれば業務の調整を行うなど
関係者がドメイン知識を共有できるナレッジ・wiki・ツールなどを整備する。

情報不足

現象

要求の理由・背景がわからないため仕様化できない。

解決策

要求の仕様化、設計が進められる粒度で要求仕様を整理・記載する。

事例

要求仕様の記載例

xx通信のデータを1秒間送信してください(※)。
前提としてxx通信のデータの送信周期は400ms。

事例の解決策

1秒間超過で良いのか、超過してはいけないのか、1秒間の範囲を明確にする。
(800msで良いのか?それとも1.2sでも良いのか?それとも1sec±xx msecじゃないと駄目なのか)

※要求仕様定義の段階で通信データの周期まで定義することは具体的すぎてふさわしくない気がしますが例ということでお許しください。
要求の仕様化のフェーズで上記の送信時間の仕様を明確にするのが妥当かもしれません。

記載の粒度

現象

記述の粒度・抽象度が統一されていない。
ある要求については抽象度が高く、別の要求は非常に具体的に書かれているなど。

解決策

記述の粒度・抽象度を要求仕様書を記載する前に決めておく。
要求仕様書もレビューが必要だと思う。

表記の揺れ

現象

類似の要求仕様の記載が統一されていない。そのために要求仕様の解釈・確認に時間がかかる。

解決策

要求仕様の解釈が一意になるよう記載する。

事例

不等号

xx-1 要求仕様: 100以上でxxが発生。
xx-2 要求仕様: 200未満でxxが発生。

xx-1とxx-2の要求仕様で条件のしきい値が異なっている。意図しているのか?それとも誤記なのか?
以上、未満、超過で動作に問題ないことは予想していたが、検証側は仕様が揺れていたら検証できない。
対策として仕様書の冒頭で要求仕様決定の理由・ポリシーを明記する、不等号で要求仕様を記載する、などが考えられる。
要求仕様を記載する側は読み手に複数の解釈を与えない、一意の意味となるような記載をすると良い考える。

目的ではなく手段が記載

現象

要求仕様が【目的】ではなく【実現手段】が書かれている。

解決策

目的ベースの表現(〜したい)で要求仕様書を記載する。

事例

2値(たとえばスイッチのON・OFF)の情報を要求仕様書に表現する際に【xxxフラグ】と記載している。
【xxxフラグ】は目的ではなく、プログラムの実装にフォーカスした表現だと思う。
要求仕様書の記載をそのまま実装でも適用しフラグにする、ということも起こるかもしれない(設計・実装工程で検討した結果、フラグにするのが最適であればそれで良いと思う)。
フラグにするか・否か最適な実現手段は要求仕様の定義より後の工程で設計者が検討することと考える。

仕様書の体裁

現象

要求仕様書の体裁・書きっぷりの話。
要求仕様書は対象装置・システムの要求が書かれているのでそれなりにボリュームがある資料になると思う。結果、どこに何が書いてあるかすぐにわからないことがある。

解決方法

すぐに要求仕様を見れる・検索できるよう目次、見出し、リンクをつけ必要な情報に早くアクセスできるような工夫をする。

次回予定

要求仕様書を正しく理解する は如何でしたでしょうか?
読んでくださった方になにかお役にたてると嬉しいです。
よければ感想などをコメントくださるとありがたく、猫のように喜びます。

次回の自社向け勉強会は6/16(木)に開催を予定しています。その頃にまた勉強会の内容を記事化したいと考えています。
勉強会の内容はつぎを考えています。

要求仕様の理解　★いまここ
要求仕様の定義・仕様化　※次はこれ!!!
設計
テスト
実装

今回は冒頭書いたテーマ 【既存組込み製品のマイコンを移植する】 に依存しない汎用的な内容を書きました。
次回はテーマに沿って 要求仕様の定義・仕様化 をやってみようと考えています。

最後まで長文を読んでいただきありがとうございました。良ければ次回もよろしくおねがいします。