仕様／設計レビュー手法

はじめに

※本記事は、以前Qiita:Teamで社内向けに投稿した内容を一部修正したものです。

以前、弊社開発チームにレビューの実施状況についてアンケートを取ったのですが、その回答を見て感じたのは、レビューの必要性については認知されているものの、 レビュー手法が確立されていない ことで、各チームとも苦慮しているということでした。

そこで、書籍や私が所属するチームでの取り組み、知見を基にレビュー手法をまとめてみました。
どうすれば効率的にレビューが行えるかということに主眼をおいてまとめています。
チーム事情により、そのまま採用することは難しいと思いますが、少しでも参考になる部分があれば、取り入れていただければ幸いです。

参考書籍

間違いだらけの設計レビュー
森崎 修司 著
http://coin.nikkeibp.co.jp/coin/itpro-s/book/dtl/nos077.html

仕様／設計レビューの目的

まずは、仕様／設計レビューを行う目的について共有しておきます。
問題が発生した場合の修正コストは、下流工程に行けば行くほど大きくなることが知られています。
特に仕様漏れや設計ミスなどで手戻りが発生すると、プロジェクトの計画に影響を及ぼしかねない膨大な修正コストが発生します。
上流工程で問題を検出し、下流工程での問題発生を未然に防止することがレビューの大きな目的です。

↓の資料では、上流工程の強化が信頼性（品質）の向上につながることがデータに基づいて示されています。

ソフトウェア開発データが語るメッセージ
「設計レビュー・要件定義強化のススメ」
～定量データに基づくソフトウェア開発のプロセス改善を目指して～
http://www.ipa.go.jp/files/000058505.pdf

仕様／設計レビューのフロー

レビューは、以下のフローで実施します。
０．事前準備
１．ドキュメントの作成
２．チェックポイントの取りまとめ
３．レビューアの選定
４．問題の検出
５．レビュー会議
６．検出された問題の修正と確認
７．レビュー品質の検証と改善

０．事前準備（作業担当：リーダー、開発責任者）

レビューを効率良く進めるため、事前に以下の準備をしておきます。

仕様書テンプレート

以下の項目を備えたものを用意します。

• 機能概要（機能の概要の説明）
• 目的／ねらい（この機能を提供する目的やねらい）
• 前バージョンからの変更点
• 競合商品との相違点
• ターゲットユーザー
• 動作条件
• 制限事項
• 未決事項
• システム構成
• 目標品質（性能も含めて最低限確保する品質の目標値）
• コマンド情報（名称、呼び出し経路、グレーアウト条件）
• 画面図
• 入出力項目（コントロール種類、ラベル、データ型、初期値、有効値、桁数、グレーアウト条件、アクセスキー、アクション）
• 変更履歴

レビューシート

以下の項目を備えたものを用意します。
レビュー効率を上げるため、レビューシートは参加者全員が共有できるようにします。

＜レビューシート項目＞

• ビュー対象（ドキュメント名、在所）
• レビュー会議日時
• レビューイ
• レビューア
• 指摘者
• 指摘日
• 指摘箇所
• 指摘内容
• 問題レベル（重大、普通、軽微）
• 修正方針
• 修正担当
• 期日
• 修正内容
• 修正日
• 確認担当
• 確認日

＜レビューシートを共有することにより得られる効果＞

• 指摘の重複を避けることによるコスト削減
• 他のレビューアの指摘を見ることによる気づき

レビュー順序の決定

手戻りを防止するため、レビューは他への影響が大きいものから実施します。

１．ドキュメントの作成（作業担当者：レビューイ）

高品質のドキュメントを作成することで、レビュー全体の効率を上げることができます。

高品質のドキュメントとは

• 読んだだけで理解できる（口頭による説明を必要としない）
• 読み進めやすい（１文書にまとまっている、誤字脱字、文章の誤り、曖昧な表現がない）
• 必要事項が網羅されている

ドキュメントの品質を高めることで得られる効果

• 説明コストの削減
• レビューアのレビュー時間の削減
• 指摘件数が減少することで、指摘に対する修正／確認コストの削減
• 将来の引き継ぎコストの削減

高品質のドキュメントを作成するためのポイント

＜テンプレートを使用＞

仕様書の場合は、漏れを防止するため必須事項が記載されたテンプレートを使用します。

＜わかりやすく記述する＞

わかりづらいドキュメントは、理解するのに時間がかかりコスト増につながります。
文章だけで説明するのではなく、箇条書き／図／表などを効果的に利用します。

• 箇条書き（条件の列挙など）
• フローチャートやシーケンス図（処理の流れの説明など）
• 図（画面図、モジュール構成図、クラス図など）
• 表（入力項目一覧など）

＜１つの文書にまとめる＞

差分開発する場合、その部分だけの仕様書を作成しがちですが、仕様全体を確認したい場合に、どれを参照すれば良いかが分かりづらく非常に手間がかかります。
特別な事情がない限り、仕様書は１つにまとめ、差分は変更履歴などで管理するようにします。

＜未決事項の明記＞

未決事項は、レビュー開始までにできるだけ解決しておきます。
間に合わない場合は、その旨ドキュメントに明記し、レビュー対象から除外するなどの措置を行います。
そうすることで、レビューアが余計な指摘にコストをかけずに済みます。

＜曖昧な表現を使用しない＞

曖昧な表現はレビューアを混乱させ、コスト増につながります。
参考書籍では、以下が曖昧語とされています。

曖昧語	対応
など	該当する要素をすべて書き出す。
これら／それら	指し示す言葉に置き換える。
処理する／対応する	具体的に何をするのかを書く。
考慮して／踏まえて／基づいて	どの程度加味するのか、どのように利用するのかを書く。
通常は／基本的には	例外となるケースを書く。
できる限り／可能な限り	許容範囲を書く。
十分な／余裕を持って	具体的な数値を書く。
すぐに／ただちに	直後なのか、若干の猶予があるのか具体的に書く。
現在の／最新の	どの時点が基準なのかが分からない。タイミングを具体的に書く。
現状通り	「現状」がどういう状態かの説明を書く。

＜誤字脱字／文章の誤り／表記ゆれ（用語の不統一）の除去＞

誤字脱字や文章の誤りが多いと、レビューアのモチベーションが低下し、重大な問題を見逃すリスクが高まります。
レビューアが問題の検出に集中できるよう誤字脱字、文章の誤り、表記ゆれは事前に除去します。
ワープロ文書なら文書校正機能を利用すると良いでしょう。

＜セルフチェック＞

ドキュメントを提出する前に、上記ポイントについてセルフチェックを行い品質の向上を図ります。

２．チェックポイントの取りまとめ（作業担当：レビューイ、リーダー）

レビューアの負担を必要最小限にするためにレビューアに提供する情報を取りまとめます。

• 重点的にチェックしてもらいたい箇所
• レビュー観点／チェックリスト
• レビュー対象／除外項目

３．レビューアの選定（作業担当：レビューイ、リーダー）

レビューアは、以下の候補から3～5名を選定します。
チーム内に有識者がいない場合はチーム外からの招聘を検討します。
レビューの依頼は、会議の少なくとも1週間前に行います。

種類	リーダー	有識者	チーム内の技術責任者	開発責任者
仕様レビュー	必須	必須	推奨	必須
設計レビュー	必須	必須	必須	任意

４．問題の検出（作業担当：レビューア）

依頼された内容に基づき問題の検出を行います。
問題の検出作業は、会議までに完了します。

検出する問題を絞る

レビューの目的は、上述の通り、下流工程での問題の発生を抑制し、プロジェクトの全体コストを下げることにあります。
検出すべき問題を全体コストに影響する重大な問題に限定することで、レビューコストを抑制します。

＜検出すべき問題＞

• 仕様漏れ
• 実現性、作業効率に関する問題
• 操作性、使用性、性能に関する問題
• 拡張性、保守性に関する問題
• 見逃すと重大なインシデントとなる問題（法令違反、情報漏洩、サービス停止）

＜積極的に検出しない問題＞

• ドキュメントの誤字・脱字
• 言い回しなどの文章の誤り
• 用語の不統一
• エラーメッセージやラベルなどの表記の誤り
• ニーモニックの重複

問題検出のためのチェックリスト（仕様書）

• 要件を満たしているか？
• 仕様漏れはないか？
• 想定条件に問題はないか？
• ユーザーの立場でユーザーインターフェースが設計されているか？
• 入出力仕様に問題はないか？
• エラー処理に問題はないか？
• セキュリティ上の問題はないか？
• 著作権や特許侵害の危険性はないか？

問題検出のためのチェックリスト（設計書）

• 使用するモジュールやライブラリが明記されているか？
• 仕様書に記載されている内容が実現できているか？
• 想定条件に漏れはないか？
• 異常系の入力に対して対処ができているか？
• 性能目標が達成できるか？
• より低コストでの実現手段はないか？
• 必要に応じて処理が共通化されているか？
• 必要に応じて既存ライブラリが利用できているか？
• セキュリティ対策に問題はないか？
• エラー処理に問題はないか？
• ログ出力のタイミング、出力内容に問題はないか？
• ライセンス違反はないか？

５．レビュー会議

会議の進め方

進行役と記録係を決める

通常は、リーダーが進行役、レビューイが記録係を務めますが、人員に余裕があれば専任の記録係を手配します。
進行役は、議論が脱線しないように進行をコントロールします。

検出した問題を共有し修正方針を決める

指摘者が問題の内容を説明し、参加者で修正方針について議論します。この際、重要度が高い問題から扱います。
決定した方針は、修正担当／期日／確認担当を決めた上で、レビューシートに記入します。
議論中に気づいた問題は、その場でレビューシートに記入し、他の問題と同様に処理します。
修正方針の決定に時間がかかる場合は、別途検討することとし、会議の進行を優先します。
時間内に問題の確認が完了しなかった場合は、会議を延長するか日時を改めます。

決定事項の確認

会議の終わりに記録係が決定項目を読み上げ、間違いがないか確認します。

会議の効率を上げるポイント

• 進行役と記録係を決める
  進行のコントロールと決定事項の管理漏れを防止。
• ドキュメントの内容の説明は行わない
  説明コストを削減。
• 重要度が高い問題から処理する
  他への影響が大きい問題から処理することで手戻りを防止。
  軽微な問題は議論の対象としないのもアリ。
• 会議時間は最長でも2時間まで
  集中力低下によるミスを防止。
• 問題が検出された原因の追及は会議終了後に当事者だけで行う
  教育的観点から問題が検出された原因を追及しがちだが、関係ないメンバを巻き込まない。

６．問題の修正と確認（作業担当：修正担当、確認担当）

会議終了後、修正担当は指摘された問題の修正に取りかかります。
再レビューを実施するかどうかは、リーダーと相談して決定します。
修正が完了したら必要事項をレビューシートに記入し、確認担当に連絡し確認を依頼します。
確認担当は修正内容を確認し、問題がなければ必要事項をレビューシートに記入し確認を完了、問題があればフィードバックします。

７．レビュー品質の検証と改善（作業担当：リーダー、開発責任者）

レビューが適切に行われたかどうかを検証するため、レビュー後に発生した問題がどのフェーズで混入したかを管理します。
（チケットやissueにフィールド等を用意する）
プロジェクト終了後（場合によっては即時）に集計し、レビュー品質に問題があったかどうかを検証します。
問題があった場合は、チェックリストの見直しなどの改善策を検討、実施します。
あくまでも改善のための管理です。レビューアの責任を追及するためではありません。

• 仕様策定フェーズ（仕様レビューに問題があった可能性）
• 設計フェーズ（設計レビューに問題があった可能性）
• 実装フェーズ（コードレビューに問題があった可能性）
• QAフェーズ（コードレビューに問題があった可能性）