アドベントカレンダー2日目ということで、投稿いたします(もう3日？いいえ２日のロスタイムです。ワールドカップ期間中ですし！)。
この記事の読者
要件定義・基本設計・詳細設計...とソフトウェア開発工程のうち、基本設計について書いていこうと思います。
設計ということで今回は守備力よりの話になります。
スタートアップでイケイケイゴーゴーやっている人にとっては物足りないかも、SIerやSIerに興味ある人向けですかね。
なお、基本設計成果物としては、API/テーブル/画面定義...etcありますが、今回は個々の成果物の言及ではなく、もう少しマクロな視点から書いていこうと思います。
設計とは
Wikipedia先生のたまわく、設計とはこういう定義です。
建築物や工業製品等といったシステムの具現化のため、必要とする機能を検討するなどの準備であり、その成果物としては仕様書や設計図・設計書等、場合によっては模型などを作ることもある。
もう少し砕けた言い方をすると
チームでの認識を合わせるためのコミュニケーションツールの一つであるとも言えますし、一種のプロトタイプと言っても良いと思います。
そのため、一側面だけ見ると具体的であればあるほどいいとも言えます。が、具体的に書きすぎるとメンテナンス性が悪くなるなどフットワーク・生産性が悪くなり、結果品質に影響与える結果を招きかねません。
一般的には外部設計などというようにユーザーや運用者、ドメインエキスパートが理解したりレビューできる程度に記載するのがいいと思います。
別の見方をすると
詳細設計(内部設計)は誰に対象にするかということを考えれば、書きやすいかもです。
プログラマー向けの設計ということで、関心事はif文やfor文を書けるような成果物ということになります。
うまい付き合い方
多少触れましたが、過不足なく表現できかつ、生産性(執筆〜レビュー、改修...)を損なわないのがいい設計書です。
そのためのコツとしていくつか紹介しようと思います。
成果物を引き算する
気合い入れて標準・お約束どおり、仕上げたくなるかもですが、
ただ、チームとか作ろうとしているものの規模によります。規模が大きくなるとコミュニケーションコストが甚大になるため、それを防ぐために書きすぎぐらい仕上げる現場もあります。
また、ある程度経験値の高いメンバー・ドメインエキスパートに近いメンバーでチーム構成することによっては書く量を減らせたり、体勢によって工夫できる点はあるかと思います。
そのフォーマットは扱いやすいか
思考停止でエクセルフォーマットに落としていませんか？
元々ドキュメント書くのに適した仕様でもあるため、マークダウンやhtmlにも十分機能しうると思います。
とくにhtmlはjsonをロードしやすいので、コードとの親和性が高いです。
何よりテキストデータのため、Git管理が非常に楽です・レビューがしやすい(OfficeファイルはZIP形式で展開するのにツールが必要)。
コードドリブンな仕組みに任せてみる
どんなに頑張って設計したところで結局動くものはプログラムでしょ、ということでツールやサービスに任せてコードと一致する設計書生成をこころみてはいかがでしょう。
我々がよく採用するのは、Swaggerなどopen APIのフォーマットを利用したり、Schema Spy(最新JAVAでは動かなかったような気がしますが。)やData Gripでテーブル定義を作成したりなどです。
Figmaなどデザインツール・システムを利用して作業の一部を別領域に棚卸ししても良いかと思います。
最後に
つらつら書き連ねてみましたが、いかがでしたでしょうか。
色々書いておいてなんですが、私自身も確立されたスタイルがあるわけではなく、日々発生するツールやサービス、考え方に影響を受けながら、絶賛模索中です。
おじさんエンジニアの経験がみなさまのよりよい開発ライフに役立つことを祈っております。