勘と経験と読経

略すとKKD。ソフトウェア開発やITプロジェクトマネジメントに関するあれこれ。

てにをは症候群とその処方箋

ソフトウェア開発プロジェクトでは、ソフトウェアを作る以外に、ドキュメントも作成する。仕様書とか設計書と呼ばれるものがそれで、ソフトウェアが満たすべき条件などが書かれている。なぜこういったドキュメントを書くのかというと、ソフトウェアそのものを作ってから手直しするのが手間だからだ(手直しが簡単ならばドキュメントなど作らずいきなりソフトウェアを作ったほうが合理的)。

ドキュメントを作成すると、そのドキュメントを何らかの形でレビューする。執筆者の思い込みや勘違いを訂正するのが目的だ。問題が発見されたら同じような間違いが他に無いかを調査、是正する。そうすることによってドキュメントの精度を上げる。

ドキュメントのレビューの際に、「てにをは」レベルの指摘を大量に挙げる人が出てくることがある。この現象を「てにをは症候群」と呼ぶことにする。

目的が共有できていない

設計ドキュメントを作成しレビューする目的は、あとでソフトウェアを作ってから手直しするのが手間だからだ。つまり、ドキュメントはソフトウェアが正しく作れる程度に正確であればいい。

設計は指針であって、指図ではない
アジャイルプラクティス 達人プログラマに学ぶ現場開発者の習慣

目的を共有していない人がレビューをすると、目の前に示されたドキュメントの品質を最大まで上げようとする。特にプログラミングの経験がない人や、ソフトウェア開発の専門家ではない顧客がレビューをすると、「てにをは症候群」が発病する。「どこまで正しい文書にすればいいのか」 の基準がわからないから、重箱の隅にあるような間違いもとりあえず指摘してしまう。一つの文書に沢山の指摘をして、「全体的に文章の質が低い」と言ったリする。プロジェクトの本当の目的はソフトウェアを作ることだったのに、いつのまにか「質の高い文書を書く」プロジェクトになってしまう。

指摘をされてから「この指摘は品質には影響が無いので修正しない」という抗弁は難しい。そもそもソフトウェアは完成していないのだ。また、一見すると同じような「てにをは」レベルの指摘の中には、重要な(品質を左右する)ものもある。

成果物と完成品

この問題に拍車をかけるのが、契約上の「成果物」の扱いである。設計ドキュメントが成果物として契約に記載されていると、契約を履行するために「完成品」を納入する必要が出る。ソフトウェアに関して言えば、実はプログラミングが完了するまでが一種の設計プロセスである(つけ加えておくと、製造はプログラムコードが動くもの―実行ファイル―に変換されるプロセスを指す)。これは一般的には理解しにくい。

ソフトウェアが動くようになるまでは設計ドキュメントはぜったいに「完成品」ではない。最初に作成された段階ではあくまで中間成果物であって、完成したものではないのだ。この点について顧客と開発者の間で合意形成していないと、「てにをは症候群」の発症の確率は上がってしまう。

もし、設計ドキュメントを「完成した成果物」として作成する必要があるのであれば、ソフトウェアが完成し、テストが完了してからがいい。とはいえソフトウェアが完成した後に、どれだけ設計ドキュメントに必要性があるのかはよく確認したほうがいい。運用・保守作業や対監査の観点で設計ドキュメントを完備することが求められることはあるけれど、必ずしも求められるものイコール設計ドキュメントではない。場合によっては、用途や目的に即した(完成したソフトウェアに基づいて作られる)運用・保守向けのドキュメントや監査向けのドキュメントを書いたほうが効率が良い場合もある。

「てにをは症候群」に対する処方

以上をもって、次のプロジェクトではドキュメントレビューを行う場合には、まず目的を明確化し、レビュアと共有することをしてみようと考えている。例えば簡単でもこのようなルールを合意しておくと、「てにをは症候群」が防げるのではないか。

  • この○○レビューの目的は、最終的に作成されるソフトウェアの品質を向上することである。ドキュメントそのものの質を上げることではない。
  • レビューでは、ソフトウェアのバグが混入するリスクの高い欠陥を集中的に摘出することが目的である。
  • ソフトウェアへのバグ混入を防ぐためには、特に以下の観点で文書をレビューすることである。
    • 合目的性
    • 仕様の統一性
    • 仕様間の整合性
    • 可読性/理解容易性
    • 一意性
    • 試験性