私自身、この仕事を７〜８年やっておりますが、設計書作成については常に悩まされておりました。
設計書のメリット・デメリットとしては以下のようなものですかね。
メリット
- メンバー間での仕様の認識を統一できる
- 出戻りを防ぐことができる
- 開発進捗の遅れの影響を防ぐことができる
- 責任の所在を明らかにできる(請負契約の場合)
- 外部に委託することができる
デメリット
- 形式的に作られているものも多い
- 現実の開発との差分が出てしまう(更新する文化が廃れてしまう)
- 作っても費用対効果が良くない(作る時間に回した方がいい)
Contents
対策
設計書はコードから起こす
現実のシステムとの差分が起こらないように、ER図であればschemaから起こすとか、API仕様書であればLaravelの(Laravel API Documentation Generator)みたいなツールですかね。
要は作るのに手間がかからない、自動化されているのであれば文化として廃れることがないので、これが一番いい気がします。
設計をした方が工数がへる、楽
設計をした方が工数がへる、ラクということになればみんなその通りにやるので、この仕組みを取り入れるのがらくな気がします。
分業する場合はどうやっても作るしかないので、必要性が出てきます。
設計→コードの仕組み化
コードから起こすといっても限界があると思うので、ある程度の仕組み化が必要になってくると思います。
一般の仕事の仕組み化と同じですが、できるだけ個人の意識に頼ることは防ぎたいので、レビューのプロセスを経ないと次のプロセスに移行できない。みたいな仕組みとして存在するパターンですかね。
個人的に必要だと思っている設計書について
ダミーデータ付き+テスト仕様書
えーこれはまだ見たことがないので、理想論です。
一般のテスト仕様書って形式的なものが多いと思うのですが、ダミーデータがあれば状態の復元がすぐにできますし、開発をする上でものすごく楽になります。
イメージとしてはPHPUnitの中に組み込む感じで、そこから仕様書を復元できるようにすることですかね。
夢物語と思っていましたが、migrationを組み込んでおけば前提となるマスタデータなどを入れておき、そこからデータを入れることは難しくないのでは・・?と思いました。
API仕様書
昨年度のプロジェクトで作ってました。フロントのエンジニアと一緒に仕事をするときに開発が出来上がってないときに、
- まずAPIのINとOUTの形だけ決める
- テストデータでリクエストとレスポンスの形を決めておく
これだけで仕様書の出来上がりです。
グルーピングされたER図
グルーピングということが重要なのですが、ER図があればデータの移り変わりなどがイメージできるのでやはりあると仕様の理解が格段に進みますね。
ER図自体の作成はwinだったらA5SQL、Macならwwwsqldesignerが簡単で便利です。
