PG日誌

受託系 PG が C# の事を書いています

仕様書が無い!!!

ぎゃふん!本当に思い知らされました。仕様書の大切さ…。

何が起きたか?

ある程度の大きさのシステム(100M超)で使われているコンポーネントを他のシステムでも使いまわす事が出来るか(もし無理なら[仕様|設計|概念])が転用できないか調査する業務をしていました。どころが「仕様書」が全くない。探しても目的の仕様書が全く見つからない。詳細設計書とテキストのメモはこそこある。が、肝心の設計書が全くない。結局(知りたくもない)長い歴史を紐解いた結果、「欲しい仕様書が存在しない」という結論に達してしまいました。

詳細設計書は要らない!

無いと書きましたが…あるにはあるんですね。仕様書。詳細設計書(数年前のもの)みたいのが結構…。数冊あって各々結構なページ数があるようです。もう、コードと処理を一生懸命日本語で説明しようとしているものが…。ただねぇ、それコード見た方が早いんですよ。数年間メンテされてない詳細設計書ってもう腐ってますよね。腐臭が漂ってます。冒頭見ただけで中身はあまり見ていません。

本当にほしいドキュメントとは?

翻って本当に欲しい情報は何か?既に出来上がったシステムを見るとよく分りますね。
・「要件定義書」: システムの背景とか主旨
・「外部設計書」:システムのおおよその構成とか、データ構造、外部要素との規約

です。これが無いと後からいくらプログラムだけ見ても何の意味も分からない事が多いです。今回の場合コードの量は多いですが該当箇所の特定までは早々にできたのでその部分のコードから外部仕様を逆に復元して、文章化から始まりそうです。。。非常にめんどくさいし知的好奇心が一ミリも刺激されませんね。

仕様書をこれから書く人へ

これからせっかく、時間をかけてドキュメントを書くのに、後から誰にも活用されない「役に立たないドキュメント」作る必要はありません。これから仕様書を書く人はぜひ、内部使用とか中身の説明じゃなくて外身の説明をするようにしてください。外部仕様書書いてください。

マジで頼みます。