5つのノウハウで徹底解説!5分でわかるドキュメントレビューの観点

ドキュメントレビューなんて面倒くさいもの、この世から消えて無くなってしまえ!」

そう思っているエンジニアの方は、きっと多いのではないでしょか。ここではそんなエンジニアに向けて、「このポイントを押さえておけば、ドキュメントレビューはスムーズに実施できる」というノウハウを、こっそりお教えします。

20160608_1

目次

  1.  1. ドキュメントレビューとは
  2.  2. ノウハウ1. 「あいまい表現」を徹底的につぶす
  3.  3. ノウハウ2. 「ソート順」の仕様が不足していないか
  4.  4. ノウハウ3. 「誤字・脱字・表記の修正」と「内容のチェック」は分けて実施する
  5.  5. ノウハウ4. すぐに代替案が出そうにない場合は、いったん議論を打ち切る
  6.  6. ノウハウ5. 紙に印刷したものをチェックする
  7.  7.  基本をきちんと守って、効率の良いドキュメントレビューを
  8.  

    ドキュメントレビューとは

    ドキュメントレビューとは、システム開発の業務で作成された各種書類や仕様書などの成果物を、第三者の目によってチェックするためのものです。その工程は、システムの品質を高めるために無くてはならないものです。

    しかし、「どういった観点でレビューしたらいいか分からない」「時間ばかりかかって、あまり効率よく誤りを発見できない」などの理由から、苦手意識を持っているエンジニアは少なくと思います。

    では、どのようにすればドキュメントレビューをスムーズに実施できるのでしょうか。
     

    ノウハウ1. 「あいまい表現」を徹底的につぶす

    20160608_2

    「○○を下回る」

    こういった表現を目にした場合、あなたは「○○以下」「○○未満」のどちらだと考えるでしょう。読み手によって解釈が分かれてしまいそうですね。このような「あいまいさ」を含む表現、システム開発の現場では、トラブルの原因となってしまう可能性があります。

    たとえば、ドキュメントの作成者は「○○以下」だと考えてこの文章を書いたのに、プログラムを書く側はこれを「○○未満」だと読みとり、実装してしまう危険性があります。そうなってしまった場合、当然のことですが、そのプログラムは数値の境界値にバグを抱えたものになってしまうのです。

    こうした事態を防ぐためには、「あいまいな表現を、明確な表現に置きかえる」「数式や論理式で表現する」などの方法を採用します。こうすることで、だれが読んでも同じ意味に解釈してもらえる文章になるのです。

    ノウハウ2. 「ソート順」の仕様が不足していないか

    20160608_3

    以下は、ある設計書の一部を抜粋したものです。

    ・会員情報テーブルの「入会年月日」が、画面から入力された「入会年月日(From)」以上、「入会年月日(To)」以下のデータを取得し、一覧画面に表示する。
    ・表示項目は、会員情報テーブルが持つ「会員ID」「氏名」「住所」「電話番号」「入会年月日」である。
    ・表示データは、1ページに最大10件とし、それ以上の件数となる場合は「前ページ」「次ページ」ボタンを表示し、ページング処理を行う。

     
    一見、何の問題も無さそうにみえる設計書ですが、この設計書には重大な記載漏れが発生しています。それは、「どの項目でソート(データの並べかえ)をし、表示するか」という情報です。

    画面や帳票に表示するデータのソート順は、設計書で漏れやすい仕様の代表格。ソート順について何も書かれていない場合、プログラマは「会員ID」「入会年月日」などの降順でソートするものと思いこみ、勝手に実装してしまいがちです。

    しかし、もしかするとプロジェクト最終版でのシステムテスト時、システム発注者が「氏名の50音順でソートさせてほしい」という要望を出してくるかもしれません。そうなった場合、会員情報テーブルに氏名の「ふりがな」を格納できなければ、DB設計からやり直さなければいけない事態となってしまい、膨大な手戻りが発生してしまいます。

    そういった手戻りを防ぐために、ソート順に関する仕様は必ずチェックしておきましょう。

    ノウハウ3. 「誤字・脱字・表記の修正」と「内容のチェック」は分けて実施する

    20160608_4

    レビューのさいに、チェックすべき観点は主に2つあります。それは「誤字・脱字・表記の修正」と「内容のチェック」。しかし、一度のレビューでこれら全てを実施してしまうと、チェックすべき点が膨大になってしまい、結果、誤りを見落とす事態が起こってしまいがちです。

    これを防ぐためには、「誤字・脱字・表記の修正」もしくは「内容のチェック“だけ”を行うレビューを、複数回実施することです。こうすることによって、レビューする側はチェックすべき点が少なくなり、より集中して誤りを発見することができるからです。

    ノウハウ4. すぐに代替案が出そうにない場合は、いったん議論を打ち切る

    20160608_5

    レビュー会議が長くなる原因のひとつとして、設計内容に誤りが見つかった場合に「では、どうしたらいいか」という代替案を決めるための議論が長引いてしまう、というものが挙げられます。

    とりわけ、ミーティング参加者が設計スキルの高いメンバーだった場合、エンジニアとしての好奇心がくすぐられ、議論の歯止めがきかなくなってしまうケースは多いものです。

    そうした事態を防ぐためには、議論が長引きそうな気配を見せた場合、いったんそれをストップし、別の場を設けて再度議論する、というテクニックがあります。

    一度冷静になって考えることで、より良いアイデアが浮かびやすくなる。感情的になることを避けることができるなどの副次的効果があり、ミーティングを効率化することができるのです。

    ノウハウ5. 紙に印刷したものをチェックする

    20160608_6

    多くの方が実感しているかと思いますが、人間はWeb画面上で文章を読むよりも、紙面で読んだほうが、より一層内容を理解することができます。

    事実、ノルウェイのスタヴァンゲル大学の研究者、アン・マンゲン氏の発表によると、同じPDFのテキストを、あるグループはWeb画面上で、別のグループは紙に印刷して読んでもらったところ、後者のグループのほうが理解度テストにおいて良い成績を示した、という結果が出たそうです。

    ドキュメントレビューを実施する場合にも、これが当てはまります。レビュー対象となる成果物を紙に印刷した上でレビューを実施した方が、より誤字・脱字を発見しやすく、内容の誤りにも気づきやすくなるのです。会社内で書類を印刷することが許可されている場合には、積極的に活用していきましょう。

    基本をきちんと守って、効率の良いドキュメントレビューを

    コードを書けば必ず何かが動いてくれるプログラミングと違い、ドキュメントレビューでは「本当に成果が出たのか」「正しいレビューができているのか」ということが不明確になってしまいがちです。

    けれど、いくつかの観点をきちんと守れば、その成果はぐんと向上してくれるもの。ここで取りあげたノウハウを活用して、ドキュメントレビューをもっと有意義な場に変えていきませんか?


     

    最新情報はFacebook/Twitterをフォロー!

     


この記事を書いた人:ぞの

img_zono

Webアプリケーションエンジニアとして様々な現場に参画し、多種多様な言語を習得。エンジニアとしての強みは汎用性の高さと、メンバーとコミュニケーションを取り合いながら円滑に案件を進められること。趣味は音楽と将棋。Ruby愛好家。Twitter : @zono1009

関連する記事

facebook

案件情報や最新記事をお届けします。
ぜひチェックしてみてください。