仕様書をレビューしながら考えていること

#1. はじめに
なにをどう考えながら仕様書をレビューしているかや欠陥を見つけるために拝借している先達の知見を挙げ、整理してみます。

#2. 読み手の期待値
業務で作成するドキュメントには書き手と読み手が存在し[^1]、高品質なドキュメントとは読み手にとって必要なことが簡潔かつ過不足なく書かれているドキュメントです。これは仕様書も一緒です。

仕様書の読み手にはプログラマやテストエンジニア、SQA、マニュアル作成者などがいますが、ここではプログラマとテストエンジニアにフォーカスします。

##2.1 プログラマが欲しい仕様書
["プログラマ 欲しい 仕様書"](https://www.google.co.jp/search?hl=ja&as_q=プログラマ+欲しい+仕様書)でググると「[プログラマが欲しい仕様書とは](https://www.slideshare.net/KatsutoshiMakino/ss-10068192)」というそのものズバリなタイトルの資料がヒットします。この資料はゲームプログラマ目線で記述されているのですが最低限必要な項目をp.31に列挙されていますので以下に引用します。

> - シナリオ
- 対象外
- 概要
- 詳細
- 未解決の問題
- 用語解説 

シナリオはゲームならではと思いますがドメインに合わせて例えばユースケースに置き換えたりすると良いように思います。

##2.2 テストエンジニアが欲しい仕様書
["テストエンジニア 欲しい 仕様書"](https://www.google.co.jp/search?hl=ja&as_q=テストエンジニア+欲しい+仕様書)や["テスター 欲しい 仕様書"](https://www.google.co.jp/search?hl=ja&as_q=テスター+欲しい+仕様書)、["テスト 欲しい 仕様書"](https://www.google.co.jp/search?hl=ja&as_q=テスト+欲しい+仕様書)でググってみたもののこちらはそのものズバリな資料はヒットしませんでした。

代わりにテストのしやすさから発想し["仕様書 テスタビリティ"](https://www.google.co.jp/search?hl=ja&as_q=仕様書+テスタビリティ)でググったところ「[ソフトウェアテスト勉強会～テスタビリティの高い仕様書を書こう！～](https://ameblo.jp/sendai-test/entry-11552931068.html)」という記事を見つけました。この記事で機能仕様書のテスタビリティを高める取り組みが紹介されていますので以下に引用します。

> - 曖昧さを回避する
- 理解しにくい条件や条件のモレはないか？
- 表や図を活用する
- 能動態を用いる

##2.3 記述の粒度
仕様書は書き手と読み手の間で仕様を特定できる粒度で書いてあればよいです。明示しなくてもお互いに仕様を一意に解釈できることをわざわざ記述すると読みづらくなります。

ここで問題となるのは一つのドキュメントに読み手が複数いてそれぞれの暗黙知、経験値が揃っていない場合です。例えば仕様担当者とプログラマは同じチームで長くやっていてハイコンテキストな仕様書でもプログラムを実装できる一方で、テストエンジニアは時々入れ替わってハイコンテキストな仕様書では漏れるというケースが考えられます。この場合は、ハイコンテキストで記述しつつ吹き出しや欄外を使って補足するのが簡潔で良いのかなと思います。

#3. 仕様書レビューの目的
仕様書レビューの一番の目的は欠陥摘出のフロントローディングです。後工程で見つかると修正コストが高くつくような欠陥を後生大事に抱えておく理由は何もないわけで仕様書レビューでいち早く欠陥を摘出できると思うとレビューが楽しくなりますよね？

このほかにもレビュー技術の蓄積や移転といった目的もあります。[JaSST Review'18](http://www.jasst.jp/symposium/jasstreview18/report.html)のセッションS2「[レビュー再定義](http://www.jasst.jp/symposium/jasstreview18/report.html#S2)」では(仕様書レビューに限りませんが)レビューの目的を「検査・学習・強化」の3つに整理されています。

#4. 欠陥を見つけるための作戦
[間違いだらけの設計レビュー](https://www.nikkeibp.co.jp/atclpubmkt/book/15/245560/)でレビュー順序の一番目に「漏れ」が来ていたりJaSST Review'18のセッションS1「[設計レビューで問題を叩き出せ！～QAの役割～](http://www.jasst.jp/symposium/jasstreview18/report.html#S1)」で「レビューは、書いていない事を見付ける」とあるようにレビューで摘出したい一番の欠陥は「漏れ」です(もちろん曖昧、誤りも摘出したい欠陥です)。

仕様書を眺めて目についた不備を挙げるだけでもレビューの効果はありますが仕様書に書かれていないことに目を付けるのは難しいです。そこで作戦を立てて臨みます。

##4.1 仕様書を眺める前に自分なりの期待値を挙げる
仕様書を読み始める前に、読み手の期待値やユーザー目線での期待(例：こうあって欲しい、こういうのは嫌といった仮説、想像)をアタマの片隅に置きながら書いてあって欲しいことをメモに書き出します。間違いだらけの設計レビューでは以下のような説明があります。

> 漏れについては、前述の通り、読む前に「こういう内容が書いてなければならない」というイメージを持ち、そのイメージとドキュメントの内容を比較します。

ドメイン知識や類似商品の知識があるとよいです。

##4.2 漏れやすい箇所を先回りして挙げる
新機能を追加する場合の影響範囲をモデル化して以下に示します。

- 新機能部分
- 改修の影響を受ける既存部分
- 改修の影響を受けない既存部分

![influence_the_scope_of_modification_model.png](https://qiita-image-store.s3.amazonaws.com/0/221758/8f7e3b97-fe10-e2c6-901e-8c80c6398bd8.png)

漏れには新機能の記述漏れだけでなく改修の影響を受ける既存部分の見落としもあります。機能的なものもあれば性能のような非機能的なものもあります。機能ごとに仕様書が分かれている場合は既存機能の仕様書の修正忘れや非機能要件の見直し忘れが漏れとなります。

新機能はそれ自体が魅力品質という側面がありますが既存機能は当たり前品質でありその劣化(デグレ)はユーザの不満を招くため、先回りしてレビュー対象に挙げます。

##4.3 型に着目する
ifの仕様はあるのにelseの仕様が抜けているとかフォアグラウンドの動作は書いてあるのにバックグラウンドの動作に触れられていないなど、型に着目してレビューします。

型のキーワードの例として[ソフトウェアテスト技法ドリル](https://www.amazon.co.jp/dp/4817193603)の第一章に登場する「間、対称、類推、外側」や、[富士通の七つの設計原理](https://www.google.co.jp/search?hl=ja&as_q=富士通+七つの設計原理)に登場する「対称原理、階層原理」があります。

##4.4 汎用的なキーワード
意地悪漢字、バグっぱ！、品質特性といった汎用的なキーワードからヒントを得ます。

意地悪漢字は[意地悪漢字](http://d.hatena.ne.jp/mkoszk/20110204/p1)、バグっぱ！は[バグッぱ！の解説](https://blogs.yahoo.co.jp/rem1988stores/16126456.html)、品質特性は[ISO25000](https://www.google.co.jp/search?hl=ja&as_q=iso25000)をご参照ください。

##4.5 欠陥に学ぶ
不具合を繰返さないことを狙ったレビュー観点です。過去バグや[故障モード](https://www.google.co.jp/search?hl=ja&as_q=故障モード)からヒントを得ます。

##4.6 観点の切り替え
レビュー観点の力を借りるのは見逃すとヤバいやつ(＝後工程で見つかると直すコストが高くつくもの)を見つけたいからであり闇雲に観点を広げて雑魚(＝後工程で見つけて直してもコストへの影響が少ないもの)ばかり見つけても仕方ないです。とはいえある程度の件数を出さないとヤバいやつも出てこないので雑魚ばかりになってきたら観点を切替えて見直します。

##4.7 漏れ→曖昧→誤りの順に読む
これは間違いだらけの設計レビューで紹介されている順番です。ただ、漏れを見つけるつもりでレビューを開始しても曖昧なところや誤りに気づいたときはひとまずメモします。メモせず頭の中にとどめておくとかえって気になるし何かのはずみで忘れて思い出せなくなるのももったいないです。

#5. 仕様書レビューマトリクス
これまでに挙げた作戦を集約します。

- レビュー観点
  - 自分なりの期待値(読み手やユーザの期待値の仮説)
  - 漏れやすい箇所(新機能だけでなく既存機能の影響を受ける部分も)
  - 型に着目する
  - 汎用的なキーワード(意地悪漢字、バグっぱ！、品質特性)
  - 欠陥に学ぶ(過去バグ、故障モード)
- 順番
  - 漏れ
  - 曖昧
  - 誤り

![specification_review_strategy_model.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/221758/a77a77c1-8c25-8955-96c7-03a2a6834093.png)

仕様書をレビューしていて今どのあたりを掘っているか、どこはまだ掘っていないか時々振り返ります。なお、仕様書レビューの目的は見逃すとヤバいやつを早い段階で摘出することであり網羅することは手段であって目的ではないことに注意します。網羅できるほうが望ましいとはいえ工数の制約もあるため「ここは見たけどここは見ていない」という情報を仕様書作成者やほかのレビュアーにフィードバックするのもありでしょう。

#6. おわりに
こうして整理してみると事前の仮説づくりや不具合分析を改善することでより欠陥を見つけられるように思いました。

##6.1 事前の仮説づくり
JaSST Review'18の[オープニングセッション](http://www.jasst.jp/symposium/jasstreview18/report.html#S0)で以下のリーディング技法が紹介されています。

- CBR(Checklist-Based Reading)
- DBR(Defect-Based Reading)
- UBR(Usage-Based Reading)
- PBR(Perspective-Based Reading)
- Adhoc

摘出したい欠陥をレビュー観点として挙げる技法はDBRに属するものと思いますが、仮説づくりにUBRやPBRを取り入れることでより多くの欠陥を拾える期待があります。

##6.2 不具合分析の改善
前出の「設計レビューで問題を叩き出せ！～QAの役割～」の[講演資料(PDF)](http://www.jasst.jp/symposium/jasstreview18/pdf/S1.pdf)のp.12に

> 設計ガイド・チェックリスト類
メインフレーム時代から蓄積・継承された開発や事故事例等から得た開発ノウハウの集合体

と書かれていてすごいと思いました。

[FMEA](https://www.google.co.jp/search?hl=ja&as_q=FMEA)をソフトウェアに応用した事例である「[観点を用いたソフトウェアにおけるFMEAの効率的・効果的な実施方法とその効果](https://www.ipa.go.jp/files/000057619.pdf)」にしてもそうなのですが、こういうことを行うには不具合(顕在化した欠陥;インスタンス[^2])を分析、抽象化し故障モードや[欠陥モデル](https://www.google.co.jp/search?hl=ja&as_q=欠陥モデリング)といった汎化情報にする必要があります。

筆者はBTS(Bug Tracking System)で過去バグを検索してレビューの手掛かりになるキーワードを拾うくらいなので不具合分析も並行して進めようと思いました。


[^1]: 書き手と読み手が一緒だったり読み手が将来の自分だったりすることもよくありますが…
[^2]: インスタンスや汎化情報は「[過失に着目した欠陥のモデリング －バグ分析はなぜうまくいかないのか？－(JaSST'13東京)](http://www.jasst.jp/symposium/jasst13tokyo/pdf/C4.pdf)」から拝借しています