前回公開したエントリ「開発者向けのソフトウェア設計書は必要か？ - 勘と経験と読経」へのフィードバックで、保守には設計書が必要なのではないか、というものがあった。その点については思うことがある。というわけで、保守という観点でソフトウェア設計書に関する考えをまとめてみた。ソフトウェア構築時に必要とされる設計書と、保守の際に必要とされるものは異なるのではないかと考えている。
議論の前提：仕様書と設計書
再掲になるけれども、ここでは仕様書と設計書という用語を以下のように定義する。
- 仕様書 … 開発者とユーザー(仕様決定者)が、ソフトウェアの振る舞いや動きに関してコミュニケーションするために必要な文書類のこと。
- 設計書 … 開発者どうしがソフトウェアを作成するにあたっての、構造や仕様についてコミュニケーションするために必要な文書類のこと。
そして、改めて説明する必要は無いと思うけれども仕様書は保守を行う上で維持する必要がある。ソフトウェアの振る舞いについてのユーザとの合意事項が無ければ、何が正しくて、何が正しくないのかが判断できない。ただし精緻なマニュアルの類いがあれば、代替できる可能性はある。
では設計書はどうなのだろうか？
ソフトウェア構築時の設計書と、保守で必要な設計書
経験的には、ソフトウェアの構築時の設計書をそのまま保守で利用するのには難があると考えている。
- 構築プロセスによるかもしれないけど、最初の構築時には前工程の仕様書類をインプットに並列で詳細化する形で設計書が作成されている事が多いと思う。よって、機能個別のプログラミングについては（ある程度は）詳細に記載されているが、横断的な機能間の考慮点などの記載は不十分なことが多い印象。
- 経緯にもよるけれども、プログラムと完全に一致しているかどうかは保証されていない。
- 一般論だけれども、プログラミング時の設計決定の経緯や背景などまで設計書に書かれている事は少ない。
- これも一般論だけれども、仕様書と違って設計書は数が多い。維持コストが大きいという問題もある。→組合せ爆発 - Wikipedia
むしろソフトウェア保守を考えた場合、こんな設計書が必要なのではないだろうか
- ソフトウェア構成要素の横断的な相関関係、俯瞰的な資料
- 横断的な考慮事項や、留意事項に関するコンパクトなドキュメント
- 個別機能のIO仕様よりは、IO単位（逆引き）で整理された更新仕様のまとめ
これらをソフトウェア構築以前に精度高く作成するのは難しい。むしろソフトウェアが一定程度完成したあとに、保守用のドキュメントを別に作る方が合理的ではないだろうか。特に相関関係などについては実際のプログラムコードから完全なものが生成できる事が多いと思う。
保守時に欲しい設計書以上に重要なもの
ソフトウェアを保守するのであれば、実際に動いているソフトウェアのプログラムコードが最も正確な資料だと思う。これを補完する資料があれば十分だというのが個人的な考えだ。
むしろ、ドキュメント類より以下のようなものを精度高く保持するほうが重要だと考えている。
- 不具合や仕様変更などによる修正の履歴
- 過去に発見された不具合や仕様変更に関する記録
- 技術的な将来の改善点も含むバックログ
これらが整備されていないほうが、頭が痛いと思う。
