2023-12-17  昔の自分と向き合う―未来への警告―

11月下旬から某システムの改修作業をしています。某システムは稼働を始めてからすでに14年以上が経過しています。

改修作業をする際に，自分が2009年4月に書いた仕様書を読み返してみたのですが不可解な点が多数あり困惑しました。解読に数日を費やしました。

今回の改修内容を仕様書に追記するわけですが，昔の自分と交換日記でもしているような気分になります。おやおや，未来の自分が一方的に追記するだけなので交換日記とは言えませんね。

さて私が日頃，仕様書を書く際に気を付けていることを少々。

未来への警告を書く

本来は不要なのですが，私は仕様書に経緯というか「そのときの気持ち」を書くように心掛けています。なぜ理解に苦しむ仕様になっているのか，何の事情があったのか，そもそも何を目指していたのか，なるべく書くようにしています。

このような未来への警告は，厄介な罠を避けたり同じ過ちを繰り返したりしないために役立ちます。

仕様書に嘘を書かない

仕様書に嘘が書かれていると後で読んだとき確実に混乱します。何が正しいのか分からなくなります。仕様書だけではなく，その成果物までもが信用できなくなります。

冗談や悪ふざけで嘘を書いているわけではないのですよ。仕様書の記載が嘘になってしまう原因は，実装中に気付いた仕様の間違い（仕様バグと言いますが）を修正していないからなのです。

仕様書は実装するために存在するので，実装が終わってテストも終わってさらにはリリースも済んでいるのに，後戻りして仕様書を書き直したいという気分にはなかなかなりません。

そうは言っても，嘘の書かれている仕様書は未来に甚大な被害を与えます。時間の許す限り実装と合わせて，品質を高める努力をすべきでしょう。

仕様書を詳しく書きすぎない

仕様書は細かく書こうとすると切りがないし，量が多すぎると後で読むのが大変になってしまいます。

私は某社に潜入していた時期，機械的に生成されたであろう数千ページにもおよぶ仕様書を目撃したことがあります。システムの規模を考えると明らかに過剰。まるで仕様書SPAMです。

現実的な作業時間で分析し切れない仕様書に意味があるとは思えません。