日々ブログ

日々のくらしの中で思ったこと

設計書あるある

アプリなりシステムなんかを作っていると、 設計書を書くことが多いと思うのですが、 結構書くの難しいですよね〜。
人の設計書を見てても、自分で書いたりしていても思うのですが、中々難しいです。
自分に対する戒めも含めて設計書あるあるを書いていこうかなと。
f:id:xinformation:20220114004337p:plain

やりたいことがやたらと書かれている

設計書なので、ある程度実現性が見通せたものを記述する必要があるのですが、 これが中々難しいです。
どうしても、仕様から抜け出せないんですよね。
仕様を実現するための設計を説明するためには、何を作るかからどうしても説明してしまうんですよね。
ただ、これをすると仕様書の内容を焼き直すだけになって、イタズラに量が増えたり、仕様変更が起きると仕様書と設計書の内容を書き直してそれらの整合取ったりとあとあと作業量が増えるので、なるべく記載しない方が良さそうですね。

技術解説ブログみたいになる

設計書を書いているとOSSの書き方にすごく悩みます。
OSSについての説明が延々と書いちゃう感じですね。
OSSって独自の使い方とか、専門用語とかがあってそれについて延々と解説してしまう感じですね。
せっせと書いていて気づくと、これQiitaやん!みたいなことになってたり。
技術ブログの見過ぎなんやろうか。
使い方とか丁寧に説明するのではなくて、それがソフトウェア全体のどういった立ち位置でどういうふうな役割を担っているかを書きたいですね。

ログの項目が書けない

ログって主機能から外れたものとして扱われがちなので後回しにされるんですよね。
出来上がってるものがないと、ソフトウェアの動作のどういった振る舞いを残したいかなんて決めづらいし、ソースコードに地道に追加していけば終わりでしょ?くらいの理解も多いです。

しかも、書く量が多いわりに、無くても客先に迷惑がかかるわけではないので、 主機能が実装完了できて時間があったら実装しようという風潮があったりします。

設計できていないと不具合が出た時に、必要なログが意味の無いログに埋もれたり、そもそも必要なログが取れていなくて、不具合解決ができなくてめちゃくちゃ困るんですけどね。