ykrods note

設計レビューのアプローチ

コードレビューより前にするレビューについての模索その1

はじめに

以前の記事 Webシステム開発でのコードレビューより前のレビュー でコードレビューだけじゃなく「要件定義〜設計」の成果物に対してもレビューをした方がいいのでは？ということを書いたので、今回はその続きで具体的な設計レビュー方法について書いてみました。

注釈

  1. この文章は今まで何となくやっていたものを明文化したという状態で、draft の段階と言えます。その前提でお読みください。

  2. WEBシステムが対象です

設計レビューの目的・意義

IPA の ソフトウェア開発データが語るメッセージ「設計レビュー・要件定義強化のススメ」(2017/03/31) にソフトウェア開発に対する分析がまとめられており、要約すると「設計レビューで不具合を早期摘出することで、稼働後の不具合件数を抑えることができる」ことが統計的に示されている。

不具合を減らせるのは顧客にとって幸せなはずである。また、稼働後のバグが減るということは、テストでもバグが出ることが減ることが期待でき、ひいてはエンジニアが安眠できることにつながるはずである。また(前の記事でも書いたが)実装後にコードレビューで設計上の問題を指摘するより設計段階のレビューで問題を指摘する方が効率的であり、コードレビュー時にも「意図不明なコード」が上がってくる可能性も減らせる(これはレビュワーレビュイー双方が幸せになる)。以上の理由により、目的というかもうまともに考えたら設計レビューするべきではという話になる。 1

前提条件

そもそも対象となるドキュメントが無いとレビューのしようがない。具体的にどれくらいの文章量が必要かについては、前述の「ソフトウェア開発データが語るメッセージ~ 」に記載がある

( 2.上流工程（要件定義～製作）強化のススメ から引用

目安として、設計文書化密度（注4）を16.5ページ／KSLOC以上、設計レビュー指摘密度（注5）を5.0件／KSLOC以上とすることを目指そう。

（注4）設計文書化密度:基本設計書と詳細設計書の合計ページ数÷開発規模

（注5）設計レビュー指摘密度：基本設計から製作までのレビュー指摘件数÷開発規模

KSLOCについては言語が COBOL、C言語、VB、Java なようであり、別言語でどれだけ違いが出るかは不明だが、同じくIPAの ソフトウェア開発データ白書2016-2017 の「SLOC規模と工数」のグラフ(p155) によると 1KSLOC の大体の中央値が1000人時なので大雑把には人月換算で「6.25人月規模に対して16.5ページ」というのが目安になる。 2

正直

  • 基本設計 => db設計で表やらER図を記載する

  • 画面設計 => 画面イメージを記載する

という様に文字だけでは無いので、とりあえず書いてみようくらいのモチベーションでも達成できそうな数値に思えるが、まずはこれを目標にドキュメントを作成してみるのが良いのでは。

ちなみに

量感について

上記資料では、ある程度のボリュームがないと指摘数が少なくなることも示されている。直感的にもあやふやなものに対しては「（よくわからんけど）大丈夫な雰囲気では？」など言ってしまいがちに思える。最適な量をあらかじめ判断するのは難しいし、ページ数を稼げばよいというものではないが、書かなすぎを防ぐためにページ数の目安を設定しておくのは効果があるように思える。

設計レビューの観点

まず、大枠の観点としては以下が考えられる。

  • 設計の入力となる要件を反映できているか(in)

  • 次の段階（詳細設計, 実装）の入力として十分な内容と言えるか(out)

  • 他ドキュメントおよびプロジェクト全体と整合性があるか

  • ドキュメントとして一定の品質を満たしているか

以下にそれぞれの解説を加える。

設計の入力となる要件を反映できているか

該当する要件と関連する非機能要件を満たしているかを検証する。

  • 要件

  • 非機能要件

次の段階（詳細設計, 実装）の入力として十分な内容と言えるか

要件定義段階では正常系は議論に挙がるが、異常系は蔑ろにされやすい。が、実装では正常・異常およびその境界を明確になっている必要がある。

例えば機能（画面）仕様では以下を検査する。

  • 前提条件

    • 例えばログイン済みのユーザしか見れない・対象のデータが存在する、などの記載があるか

  • 正常系での挙動

  • 異常系での挙動

  • 境界値

  • パーミッションとセキュリティ

    • 例えばECサイトで請求先（住所）を他人が閲覧できてしまうとかは常識的に考えてまずいが、設計に書いていないとうっかりユーザ情報のAPIに載せちゃうなどありえるので、ダメなものはダメと書いておく。

他ドキュメントおよびプロジェクト全体と整合性があるか

  • テーブル定義書・ER図

    • 参照するテーブル・カラムの記載がされているか

  • 用語集

    • 用語にブレがないか、用語集に記載されているか

    • 用語のブレは誤解要因なので無くした方が良いのだが、レビュー項目としては本質的でないので、設計レビューの前にセルフレビューなどで事前に無くしておくのが良い。

    • なんらかの専門分野を扱う場合、その道のプロに単語・その英訳を見てもらった方が間違いがない。

  • ユースケース記述

    • ユースケース記述のステップごとに、画面仕様と照らし合わせてステップが実行可能かを確認していく（シナリオに基づくウォークスルー） 3

    • ユースケース記述が十分であれば、基本的にそれが通れば問題がないと言えるので重要なのだが、残念ながらユースケースを網羅的に記述するのは大変なので「ユースケースを全て通せれば確実に問題が起きない」わけではない。この辺はテストと一緒で、どこまでやるかをクライアントの要求品質に合わせて決定することになるかと思う。

  • プロジェクトの目標達成に寄与する、またはビジョンに沿っているか

    • 要求段階で定める目標・ビジョンは要件・非機能要件に反映されているかもしれないが、進めている間にずれていくことがあるので適宜確認する。

  • そのた ( 開発の各工程における成果物 を参考に)

ドキュメントとして一定の品質を満たしているか

  • 同種のドキュメントの文書構造が統一されているか

  • 誤字/表記ゆれ

    • 既に書いたがこういうのはセルフレビューか校正ツールなどで事前になくす

  • 解釈の余地

    • 記述が具体的で、あやふやな表現が無いか

    • 人によって解釈が変わる様な事柄の場合、具体例として「当てはまる例」「当てはまらない例」が示されているか

実施方法

設計レビューの実施方法は対面・非対面の二つに分類できる。

対面の場合ミーティングを設定し、進行役が対象の説明を行いつつ、レビュワーがそれに対する指摘を行うような流れになる。進行・説明役をレビュイー以外が務めるとより厳格なレビューになるらしい（インスペクション）。

  • 上述のシナリオに基づくウォークスルーについては基本的には流れを通せるか通せないかの確認作業のみなので対面で行うのが良いかと思う。

  • クライアントを混えてレビュー会議を行うと明確な区切り（＝ドキュメントの承認）になるので良いと思うが、準備等ある程度しっかりやる必要が出てくる。

非対面の場合は課題管理システムなどでレビュワーに作業依頼を行い査読・フィードバックをもらう。

  • 作業依頼時に、レビュー対象と関連するドキュメントがどれで、どこにあるかを記載する

  • 時間的な制約がないので突っ込んだ指摘が得られる可能性もあるが、あまりレビュワーに期待しすぎると負担も大きくなる。レビューが大変＝そもそも情報共有や進め方がおかしいので、そういう場合カジュアルにPMに相談するのが良いと思う。

どのような形でレビューするかは、チーム・クライアントそれぞれの理解度や内容の複雑度を踏まえて判断する。この辺の段取りは要件定義段階で整えておいた方がスムーズに進行できそうに思える。

おわりに

draft なのでご指摘など頂けると幸いです。

おまけの考察

チェックシート

検査項目をより詳細にするとチェックリストとして利用することもできるが、あまり細かすぎると以下のような問題が起こる可能性が出てくる

  • 単純作業化してしまいチェックリストにない項目で見落としが出る

  • 項目が膨らんだ結果、予定した時間内に終わらなくなる

このためリストとしてはほどほどの量に留めておき、「例えばこんな視点で考えるとどうか」といった、レビュワーの考えを引き出すようなものが良いのではないかと思われる。

あるいは具体的なチェック項目をシステム管理してレビュー実施時にランダム抽出するのも有効かもしれない。

モチベーション

レビュー会議は大手ベンダーだとどうやら行われているらしいのだが、以下のような問題点もあるらしい

  • レビュー会議にあまり関係ない人を連れてきてもモチベーションが上がらない（発言するメリットがない）

  • かと言って指摘が多い人を評価するようにすると、あら探しが始まり、場が乱れる

この辺は実装者がレビュワーになれば割と改善しそうであり、実装の効率も上がりそうに思う。

イテレーション

他の資料との照らし合わせがあるので単純に一個一個ドキュメントを作り上げるというよりは全体を徐々にアップデートする形になるはずで、そうすると設計コストもアップデートに対応する分の調整コストを含める必要があるはずだが、どれくらいで見積もりするのが適切なのだろう（プロジェクトバッファを積んでおけばいいのか？）

参考

  • IPAの各種資料

  • なぜ重大な問題を見逃すのか？間違いだらけの設計レビュー [改訂版] （日経BP社, 2015年9月）

Footnotes

1

アジャイルの場合どうなのというのは残念ながら存じ上げません

2

工数(人時)が100 ~ 10,000 で分布しているので本当に大雑把。

3

このような複数人で行うシナリオベースの机上デバッグをウォークスルーと呼ぶ、という認識だったが、設計についてのインフォーマルな会議であれば割となんでもウォークスルーと呼ぶらしい。

4

画面イメージは、設計段階では(なぜか)デザインを決められないまま進めることが多いが、極力具体的に書く。そうしないと解釈にブレが生じるし、「後で修正できるでしょ」と思われてしまうとレビューする意味が薄くなってしまう。ツールとしては(既に浸透してそうだが) AdobeXD がお勧めできる。

Software Development Process 設計 レビュー

設計レビューのアプローチ — ykrods note
https://www.ykrods.net/posts/2020/12/05/review-for-system-design/

Comments

Recommends