技術とか戦略とか

SIerで証券レガシーシステムを8年いじってからSESに転職した業務系エンジニアによる技術ブログ。

設計書のメンテナンスのあるべき姿

設計書は、システム概要を指し示すために必要なドキュメントです。
設計書があれば、実装を知らない立場の人(例えば要件定義担当や上位の設計者)との意思疎通がスムーズになりますし、開発者を新たに向かい入れる時にも実装の内容をスムーズに理解してもらえるようになります。
実装を確認しなければならない時もありますが、それは詳細を確認する必要がある場合や、実際にソースコードを改修する場合に限られます。
 
----
 
ここまでが本来のあるべき姿なのですが、実際の現場では設計書をあてにせずに実装を見る文化になっている現場もあります。
そのような文化になってしまう原因は、設計書の信頼性が低いことにあります。
「設計書の信頼性が低い」というのを具体的に書くと、「設計書が実装と乖離しており、正しいのは実装の方」ということです。
そのような設計書には、情報の誤りや不足が見られます。
「情報の誤りや不足」というのは、具体的な例えを出すと以下のようなものです。
・2021年時点で消費税は10%に上がっているのにも関わらず、「消費税は8%である」という現時点では誤りとなる記述が残っている。(情報の誤り)
・2021年時点では店頭で購入できるカロリーメイトはブロックタイプ・ゼリータイプ・リキッドタイプの3種類あるのにも関わらず、「店頭で購入できるカロリーメイトはブロックタイプとゼリータイプの2種類である」という現時点では不足となる記述が残っている。(情報の不足)
 
設計書に情報の誤りや不足が見られても、実装が正しければ、今この瞬間ではユーザーに迷惑がかかることはありません。
しかし、設計書に情報の誤りや不足が見られる場合は、その設計書を元に意思疎通や実装理解を行うと、情報の伝達や理解が正しく行われず、それが将来の障害の原因になり、ユーザーに迷惑をかけることになります。
そのような障害の可能性をなくすため、設計書はあてにせずに実装を見る、という文化が生まれます。
 
設計書はあてにせずに実装を見る、という文化は、近い将来は上手く回りますが、人員が変更になるタイミングで問題が顕在化します。
開発者とその周りの人が変わらないのであれば、システム概要が暗黙知的に共有されているため、情報の伝達や理解を正しく行うことができます。
しかし、設計書がなければシステム概要が形式知にならないため、次の開発者がシステム概要を理解することが困難になってしまいます。実装を全て見なければシステム概要を理解できない状態となり、引継ぎに時間を要するようになってしまいます。
その周りの人も、人員が入れ替わった時に、実装レベルで細かく見る必要が出てきてしまいます。
将来の人員変更も考えると、設計書はあてにせずに実装を見る、という文化は、大きなコストとリスクを抱えることになってしまいます。
 
システムを運用・保守する上では、設計書のメンテナンスは欠かせないものであり、設計書がメンテナンスされ続けて実際に読まれることがあるべき姿です。
 
----
 
設計書がメンテナンスされなくなってしまう理由は、設計書のメンテナンスに工数を要するためです。
工数に余裕がない案件では、設計書のメンテナンスはどうしても後回しになってしまいます。
 
しかし、設計書のメンテナンスに工数を要してしまうのは、設計書が正しく書かれていないから、というのもあります。
もし、設計書がシステム概要を示すものではなく、実装とほぼ1対1なのであれば、設計書の記述量は実装とほぼ同程度となってしまい、記述量が多い分、設計書のメンテナンスの工数も増えてしまいます。
設計書がシステム概要を示すものなのであれば、設計書のメンテナンスの工数は少なくとも実装ほど大きくはならないはずです。
 
そして、設計書が正しく書かれているのであれば、実装の助けにもなるはずです。
実装をする際には思考の整理が必要になりますし、複数人で開発しているのであれば意思疎通も必要になります。
もし、設計書が正しくシステム概要を示すものであり、実際に実装の助けになるものなのであれば、設計書をメンテナンスした方が実装もスムーズに進むはずです。
「将来のことを考えて仕方なくメンテナンスする」という感覚ではなく、「メンテナンスされないと今この瞬間に困るからメンテナンスする」という感覚になるはずです。
 
まとめると、システム概要が示され思考の整理の役に立つ設計書を書くことが、設計書が継続的にメンテナンスされるというあるべき姿に近づくための方法である、ということになります。