結局、システムの設計書って何書けば良いの？っていう件

僕はいくつかシステムやチームに参加させてもらいましたが、驚くほど、

設計書がコスパ悪い。。。

個人的にはで、ドキュメントとして成立してないことも往々にしてあると思ってます。

そこそこ工数とってやってる訳ですから、情報資産としてイケてる設計書を作りたいのです。

という訳で、今回はそもそもなぜシステムの設計書は得てして微妙なのか考えてみました。

【微妙だと思うところ①　実装と整合性が取れていない】

これ出来てないと意味無いと思うんですけど、ちゃんとするの難しいし、もはや違ってて正常な空気すらあります。

内部設計が微妙な場合はたぶん、こういう状況でしょう。

外部設計作る→内部設計作る→内部設計間違っとるぞと思いながら正しいだろう実装をする→修正の時間ないOR忘れるOR製造終わったし放置でよくね？OR運用さん宜しく

僕は根本原因はWBSにあると思うんですよね。

実装が遅れるとか、仕様が変わるとかはリスク高いので考慮してますけど、

ユーザーへの資料でもないし実装できちゃうし、考慮してないですよね。

WBSになければ、時間ないし忘れちゃうでしょう。

内部設計が間違ってるのが分かるのは製造や単体テストのフェーズなんで、ウォーターフォール自体が失敗してるというのもWBSに書きにくい理由ですかね。

運用さん宜しくってのは、どのチームでも出来ることじゃ無いですよね。ソース読めない人もいますし。属人化やらしてるレベルだと優先順位は最下位でしょうね。

【微妙だと思うところ②　資料多すぎ。しかも断片的】

システムが大きくなれば、資料が増えるのは分かりますけど、必要以上に多くなってませんかね。例えば、プロジェクトごとに資料を新規作成している場合。

特に、システムの変更箇所のみ設計書作るとか。

2003年　[基本設計書]リンゴ画面表示対応.xls

                詳細画面の中央にリンゴを表示する。

2004年　[基本設計書]リンゴ画面表示個数変更対応.xls

                詳細画面の中央にリンゴを５個表示する。

2005年　[基本設計書]オレンジ画面表示対応.xls

                詳細画面にオレンジを２個表示する。　※リンゴ画面表示個数変更対応.xls参照

2007年　[基本設計書]画面表示切替対応.xls

                詳細画面に表示する果物をラジオボタンで切替可能にする。

2010年　[基本設計書]詳細画面改修対応.xls

                詳細画面のラジオボタンをプルダウンに変更し、管理者はバナナを選択可能にする。

2011年　[外部設計書]果物管理システムリプレース対応.xls

                果物管理画面の下部に備考欄を追加する。※要件定義書を参照

2015年　[外部設計書]みかん個数入力欄追加対応.xls

                果物管理画面の上部にみかんを表示し、個数入力欄を追加する。

。。。で、結局全体としてはどうなっちゃったの？よくわからんから、システム触ってみよ。

となるパターン。

上記の場合だと、画面名や果物名もしれっと変わってるし、バナナがどこに書いてあるのか調べるのは大変でしょう。過去の資料を参照にすると、陳腐化して使い物にならん資料も大事にとっとかないといけない。それと資料間の境目的な仕様の記載が漏れがち。実は2007年時点で果物の表示は全て１個でした。とか色々出てくる。

そして将来は、みかんの個数だけインサートするテーブルが多いとかベテランしか知らない状況が生まれるんでしょうね。

【微妙だと思うところ③　肝心なところがスカスカ】

詳細設計書に一生懸命ロジックを書くと、保守が大変なのか手を抜いてることがありますね。文章にしにくいときもあるのでこれも難しいところ。

詳細設計書曰く、

　詳細リスト取得・・・リンゴ、バナナ、オレンジについて詳細マスタからデータを取得する。

ソースコードは、

public class L001001 extends BusinessLogic {

    public void getDetailList(String userId, InfoTable info){

        switch(info.fruitsId) {

            case Const.APPLE:

                addApple();

                break;

            case Const.ORANGE:

                if(SystemUtil.getServiceID(SystemConst.S01).equals(info.serviceId)) {

                    if(!CommonUtil.isEmpty(SystemUtil.getCustomData("REMARK", "S01"))){

                        try {

                            getRemark();

                        } catch(BLException e) {

                             exceptionHander.add(e);

                        }

                    }

                }

                addOrange();

                break;

            case Const.BANANA:

                addBanana();

                break;

        }
        addRemark();
    }

}

適当だけど、こんな風になってたりする。

あれ、オレンジの時だけなんかやってるじゃん。リンゴはしなくていいの？

みたいな。嫌ですね。経験上、設計書がザルすぎるところは単体テストも適当。

かといって、１０Kステップあったら設計書に１０K行書くのも嫌です。

設計書とか関係ないけど、個人的には何でもかんでもメソッドの型がvoidなのは本当に見る気失せます。

ということで、努力目標程度ならまだしも、設計書とプログラムをバッチリ辻褄合わせるのって、本当に難しいし、そこに時間やら人やらつぎ込むのは、たぶん無理というか無駄。資金が潤沢にあればいいレベルまで持ってこれるでしょうが、UI設計とかテストとかに時間使った方が、ユーザは喜ぶと思うんですよね。

この件について、私なりの結論は、

詳細設計だか内部設計だか知らないが、ソースコードに吸収されてしまえ。

です。

詳細の記載場所はJavadocとかコメントとかにして、概要とか全体像は資料にしておく方がいいと思うので、基本設計書はしっかり作るべきです。