📘

効果的なドキュメントレビュー：問題検出のための正しいアプローチ

2024/02/16に公開

プロジェクトマネジメント

設計

はじめに

設計レビューを行う機会があり、「感覚的にレビューを行うことによる無駄な工数消費は避けたい」と考えていました。
そのため、レビューを行う際に何か意識すべきことがあるのではないかと模索していたところ、「なぜ重大な問題を見逃すのか？間違いだらけの設計レビュー」という本に目が留まりました。
これからこの書籍の一部を紹介します。
この本を通じて、レビューにおける目的を理解することが、品質を確保し、工数の無駄を避けるために重要だと感じました。

本書は四章構成となっています。

レビューの間違い
準備と問題検出
レビュー会議の進め方
さらなる効果向上

今回は「第一章：レビューの間違い」で紹介されているものから抜粋しました。

「第一章：レビューの間違い」から以下を抜粋します

1−1. レビューの目的の間違い
1−2. 問題検出の間違い

「思いつき」「数字合わせ」「つるし上げ」のような間違ったドキュメントレビューを避ける
レビューの最大の目的は、早期に問題を検出することにより、修正工数を低減させること
レビューの結果はマインドにも大きく左右される

1−1. レビューの目的の間違い

失敗レビューの典型

見つけやすい誤字脱字をどんどん指摘
指摘件数のノルマ達成でレビューは終わり
ドキュメント作成者の人格を攻撃する

【思いつき】：見つけやすい誤字脱字をどんどん指摘
レビューアの間でどんなことを指摘するかといった方針が定まっておらず、思いつくままに指摘を挙げていくこと。
「思いつくまま」なため、レビューアの得意分野に関すること、「誤字脱字」のような軽微な問題が多く挙がる。
その結果、レビューイの修正工数の多くは、軽微な問題の指摘に消費される。
その分だけ重大な問題の指摘が少なくなる。

【数字合わせ】：摘件数のノルマ達成でレビューは終わり
問題指摘件数のみを管理指標としたアンチパターン
例：

ドキュメント1ページ当たりの件数
レビュー実施1時間当たりの件数
指摘件数は、手を抜かずにレビューを実施したかどうかを判断する材料になります。
しかし、その数字のみに着目し、管理を行うと逆に手抜きを誘発していまう。
こういった数字のみに着目すると問題指摘件数を増やすことに注意が向いて重大な問題の検出が疎かになる。
ドキュメント作成者は「なんのためのレビューなのか」と困惑する

具体的なレビュー会議のシーン

管理指標で決めた下限件数を上回った途端に「こんなところで終わりにしようか」という雰囲気が漂うといったシーン
逆に件数が下限に到達しそうにないと、進行役が「あとn件足りません。なにかありませんか？」と慌て始めるシーン
それでも問題が見つからない場合には、指摘件数の水増しをおこなうようになる。
その場合、「早い/速い」のような微妙な誤植誤字を探したり、すでに挙がった問題を2つに分割したりします。

【つるし上げ】：ドキュメント作成者の人格を攻撃する
ドキュメントの内容に関する問題を指摘するのではなく、以下のように作成者の人格を攻撃します。

「こんな間違いをするなんてあり得ない」
「やる気が感じられない」
「こんな設計書をレビューしないといけない人の気持ちになってよ」
もちろん、レビューアに人格攻撃をするつもりはなくても、問題を指摘していくうちにエスカレートしていくことがあります。
レビューイも何人ものレビューアに袋叩きにされたら、たまったものではありません。
そこで、自己防衛のためか、レビューアの指摘に反発してくるケースも出てきます。
「例外処理が抜けているので追加してください」といった妥当な指摘に対しても「そんな例外は聞いていないので修正する必要はありません」と突っぱねるという具合です。

レビューの目的は修正工数を減らすこと

「修正工数の低減効果（コスト効果）」を得ることが手間や時間を割いてレビューを行う最大の目的になります。
【コスト効果の高い問題】

実装やテストの工程で発覚した場合の修正工数が膨らむ問題
将来の拡張や保守の工数を膨らませる問題

ドキュメントレビューでは、要件定義や設計といった工程で、開発するシステムの潜在的な問題を検出します。
これにより、実装やテストの後工程に入ってから問題を見つける場合よりも、修正に必要な手間、修正工数を減らすことができます。
もちろんですがレビューの実施には、工数が発生します。
レビュー会議となれば、リーダクラスや有識者といった工数単価の高いITエンジニアが集まるので人的コストはばかになりません。
そのため、実装やテストの工程で発覚した場合の修正工数が膨らむ問題は積極的に指摘する。
一方で、実装やテストの工程で見つけても修正工数が大差ない問題は積極的に検出する必要はない。
今の開発における問題だけでなく、将来の拡張や保守の工数を膨らませる問題があれば、それも指摘する。

1−2. 問題検出の間違い

時間がかかり見逃しが増える四つのアンチパターン

ドキュメントレビューでは、目的をしっかり決めた上で、各レビューアが対象ドキュメントを読みながら「問題検出」を行います。
「問題検出」する上で特に気をつけたい間違いの典型例を挙げる。

人間関係の持ち込み
作性者気分
二兎追い
時間切れ
【心構え：人間関係の持ち込み】
レビューアは、問題検出をしているときに、レビューイの顔を思い浮かべてることを行いがちです。
このような人間関係を持ち込むとドキュメントを見る目が「厳しく」または「甘く」なってしまいます。
例えば
今後の反撃を恐れ、甘い指摘
普段優秀な先輩が作成したドキュメントを信頼し、甘い指摘
生意気な後輩が作成したドキュメントは厳しく指摘
このような人間関係を持ち込むことは、程度の差はありますが、誰でもやってしまうものです。
人間関係は切り離すべきでありますが、人間は感情ある生き物ですからそう簡単にはいきません。
人間関係を持ち込まないために心がけることは、繰り返しレビューの目的を再確認することです。
「レビューの目的は修正工数を減らすこと」

【心構え：作性者気分】

レビューア自身が作り直しをやってしまう背景

軽微な問題が大量に存在し、レビューアが疲弊している場合
レビューアの技術知識や技法知識が豊富な場合

レビュー対象のドキュメントを見て、「これなら一つ一つ指摘するより、自分が作り直したほうが早いのでは？」と思うことはありませんか？
そうして実際にレビューア自身で大幅なドキュメント修正をやってしまうことがあります。
これは重大な問題の数はあまり関係なく、軽微な問題が大量にあってレビューアが辟易している場合によく起こります。
一方、重大な問題がないにも関わらず、「ここは⚪︎⚪︎⚪︎の構造に置き換えた方が良い」というように、自身の思い入れがある技術、得意な技法に置き換えてします。
これは技術や技法の知識が豊富なレビューアに起こりがちなことです。

「スキルの高い人がドキュメントを作成すること」は良いことです。
しかし、ドキュメントを作成するのがレビューアであるとレビューの原則に反します。
レビューの原則は、レビューアが「問題検出/指摘」を行い、レビューイが修正するのが原則です。
レビューアが直接修正や作り直しをすると、そのために時間を取られ、「問題検出」が疎かになってしまいます。
また「レビューアが作り直したドキュメント」をレビューする人がいなくなってしまう場合もあります。

問題がありすぎるドキュメントの場合は、作り直しを検討する必要はあります。
その場合でも、1人のレビューアが勝手に判断するのではなく、相談し決定する必要があります。
一般的に、「今あるドキュメントを活かして修正する」ほうが「1からドキュメントを作り直す」よりも最終的な工数は少なくなります。

【方法：二兎追い】
「二兎追う者は一兎をも得ず」 ということわざは、問題検出にも当てはまります。
「エラー処理の定義」、「機能間の依存関係」、「リソースの解放漏れ」といった複数の観点があるとき、それらの観点で一度にまとめてドキュメントをチェックしようとするとうまくいきません。

複数の観点で一度にまとめてドキュメントをチェックするよりも、「一つ目の観点を持ってドキュメントを通読。その後、二つ目の観点で通読」というやり方の方より良い結果を生みます。
観点を分けることで重大な問題の見逃しが減る上に、時間も短くなることが多いです。

【方法：時間切れ】
時間配分を考えずに、じっくりドキュメントをチェックすると、終盤は時間が足りなくなり、序盤と同じ精度で目を通せなくなります。
レビューアにとって、問題検出にかけれる時間は限られていることが多いです。
そのため時間切れ（時間配分のムラ）に陥らないようにするには問題検出の作業工数を見積もることが有効です。
必ずしも厳密に見積もる必要はなく、確認項目の観点に注目し、作業概算/目標を定めます。

まとめ

ドキュメントレビューにおける効果的なアプローチとその誤った方法について記述しました。
正しいレビューの目的を理解し、問題検出に集中することが重要です。
問題検出の際には、人間関係や個人のスキルに左右されず客観的な視点を持つようにしましょう。
間違ったレビューのアプローチを行うと効果的な問題検出が妨げられます。
今一度レビューする際には目的を意識するように心がけましょう。