設計書の作成はSEの腕の見せ所
設計書の作成は非常に重要なSEの仕事だ。SEは顧客とすり合わせた仕様を、システムを構築するためのInput資料として設計書にして残す。
設計書の記載が曖昧であれば後工程でプログラマーが混乱し、認識相違の原因となる。また、設計書の表現が細かすぎたり、冗長であったりすると、仕様変更が発生した際の修正箇所が多くなり、保守運用工程の生産性の低下に繋がる。
反対に、綺麗に整理されて誰が読んでも理解しやすい設計書であれば、構築そのものものがスムーズに進むだけでなく、システムを保守運用する人間が代わったとしても高い品質で維持管理していくことが可能となる。
このように設計書は、SEがシステム構築プロジェクトにおいて生み出されるシステムと並んで、価値のある成果物なのである。
設計書を記載する目的
設計書を記載する目的はなんだろうか。顧客への納品物として指定されているから？では、顧客は何故、設計書を納品物として指定しているのだろうか。設計書はどのように使われるのだろうか。最強SEたるもの、いついかなるときも目的を意識した仕事をしよう。
システムの設計書を作る目的は、
・顧客からの要望をシステムの仕様として定義した結果を残すこと
・それを次工程に繋げること
である。
言葉を変えると、設計書はコミュニケーションを円滑に進めるための道具とも言える。
設計書が正確に、わかりやすく記載されていることは、システム構築において重要な他者とのコミュニケーションを円滑化することに寄与するのだ。
設計書を記載する際の注意点
ここでは、設計書を記載する際に注意すべきポイントを、その理由とともに紹介する。
表現を統一する
設計書中に登場する言葉は統一しよう。また、一つの言葉に複数の意味を持たせることは避けよう。大規模なシステムであれば用語を定義するドキュメントを運用することも有効である。
悪い例
良い例
ガイドラインや雛形を利用する
複数の機能を分担して設計する場合など、記載の粒度や観点が属人化することを避けるために、雛形やガイドラインを利用することが有効である。
自分が設計全体を統括する立場の場合、規定のガイドラインがに沿った設計書になっている事をチェックする仕組みを検討しよう。雛形は設計者に利するため比較的、使用を徹底しやすいが、ガイドラインは設計者が毎回隅々まで参照するのは面倒な部分もあるので、慣れてくると省略されがちだ。
折角規定したガイドラインが形骸化しないよう、必ずチェックを行うようにしよう。
何故そうなっているのか、意図や背景を補記する
システムが常に美しく、合理性を優先して設計されていれば設計書を読んでその意図を推し量ることが可能だろう。
しかしながら、現実にはシステムが常に美しく設計されているということは稀で、パッチワークのようなシステムも数多く存在する。そのため、現実のシステムを構成するソースの中には、「過去の経緯で仕方なく」入っているロジックやデッドロジックが残ったままになっている場合も多い。
こうしたシステムにおいては、設計書に記載するのは結果だけでなく、その経緯や何故そのような設計になっているか、という考え方を記すべきだ。それが記されていることで、設計時の担当者と違う人間が次の修正を加えようとした際に、誤った設計をする確率を減らすことが出来るのである。
考察：システムは何故汚くなるのか
システムを構築する目的は言うまでもなく、利用者のがそれを使って何をしたいかという事に依存している。
そして、多くの場合それはビジネスでの収益となる。そのため、いくらシステムが美しく、ソースコードを短縮できたとしても
それが収益に結びつかなければ意味がない。
最もコストが低く（＝修正量が少なく、影響範囲が少ない）できる案が採択される。
そして、その案が最もシステムが美しくなる方法、とは限らない。
かくして、美しかったシステムに「過去の経緯で仕方なく」なロジックが実装されることになるのだ。
一事実一箇所を心がける
一つの設計は一つの設計書にのみ記載することを心がけよう。なぜならば、複数個所に同じ仕様を記載することはメンテナンス姓を低下させるからである。
ある仕様が複数の設計書に記載されていると、その仕様に修正が発生した際の修正範囲が大きくなり、修正漏れも発生しやすくなる。一つの仕様に対して別々の設計書に別々の内容が記載されていると、混乱の原因となるだけでなく、他の設計書の品質まで疑われてしまうことになる。
版を管理する
設計書を作成する際には必ず版管理を行おう。そして、設計書を修正する場合には1.1版 , 1.2版のように版をあげるだけでなく、どこにどんな修正を誰がいつ加えたのかということを記録して管理しよう。
設計書の版管理がされていないと、設計書が一人歩きしてしまうことに繋がる。
[st-kaiwa1]設計書にはこう書いてあるじゃないか！[/st-kaiwa1] [st-kaiwa2]その設計書は最新版ではありません[/st-kaiwa2] [st-kaiwa1]なんだと、聞いてないぞ！どこにそんなことが書いてあるんだ！？[/st-kaiwa1]
などという不毛なやり取りが発生しないように、きちんと版管理を行おう。
表や図を有効に活用する
文章で表現すること難しい仕様は表や図を使って表現しよう。下記の二つの例を見ればどちらが理解しやすいかは一目瞭然だろう。
悪い例
良い例
曖昧な表現を使わない
ビジネス文章全般に言えることだが、設計書は正確性を重視し、曖昧な表現を使うことはやめよう。受け取る人によってイメージが異なり、誤解に繋がる危険な要素だからである。
曖昧な表現の例：
約、大きい、小さい、少し、かなり、たぶん、とても、すごく、早い、多少
例外的に、参考情報として過去の経緯などの定性的な情報を付与する場合には曖昧な表現であっても価値がある場合があるが、多くの場合、曖昧な記載は無いほうがマシである。
まとめ
設計書は特にSEとしての力量の差がでやすい成果物である。注意すべきポイントは多いし、どの設計書が最高というのも明確に定義しづらく、学ぶのが難しい領域といえるだろう。
だからこそ、良い設計書を書けるSEは価値があり、最強SEを目指す以上、設計書作成術を学ぶことは避けては通れない道といえる。
本稿であげたポイントを意識することで少しでも、良い設計書を作成する助けになれば幸いである。
コメントを残す