こんにちは。
みなさま、設計書、書いていますか？
私は昔、Office製品で設計書を書いていましたが、最近はもっぱらMarkdownで書いています。
Markdownで書くなら、できればGitで管理して、プルリクエストも活用したいですね。
それをうまく運用するために、私は設計書をソースコード同様にGitリポジトリ内に配置することにしました。
今回はそのお話です。
コロケーションとは
コロケーションとは、関連するリソースを近くに置くことを指します。
コロケーションは、Next.jsの公式ページで触れられています。
コロケーション自体は設計書に焦点をあてたものではないのですが、私のチームではこれをバックエンドプログラムの設計書に適用してみたというのが今回のお話です。
もしかしたら今回やったことはどこかに書いてあるのかも知れませんが、とりあえず私のチームではコロケーションを参考に独自でやってみたと思ってください。
やってみたコロケーションのイメージ
今回はAWS Lambdaを用いたサーバーレスによるバックエンドでやってみました。
言語はPythonです。
以下は構成のイメージです。
/
├── app
│ ├── function_a
│ │ ├── handler.py
│ │ └── README.md
│ ├── function_b
│ │ ├── handler.py
│ │ └── README.md
│ └── function_c
│ ├── handler.py
│ └── README.md
├── docs
│ ├── database.md
│ └── system_diagram.drawio
└── README.md
機能＝AWS Lambda関数ごとにディレクトリを作り、その中にhandlerと設計書となるREADME.mdを置きました。
README.mdにマークダウン形式で設計を書いていきます。
機能をまたぐ設計や、構成図・データベース設計などはdocsディレクトリに配置しました。
このような構成にした理由
今回の構成の始まりは、設計書をマークダウンで書きたい、プルリクエストを活用したいというところから始まっています。
構成を検討する過程で、以下のパターンも議論しました。
/
├── app
│ └─── functions
│ ├── function_a.py
│ ├── function_b.py
│ └── function_c.py
├── docs
│ ├── database.md
│ ├── function_a.md
│ ├── function_b.md
│ ├── function_c.md
│ └── system_diagram.drawio
└── README.md
/
├── app
│ └─── functions
│ ├── function_a.md
│ ├── function_b.md
│ ├── function_c.md
│ ├── function_a.py
│ ├── function_b.py
│ └── function_c.py
├── docs
│ ├── system_diagram.drawio
│ └── database.md
└── README.md
上のパターンは、ソースコードと設計書が離れており、あまりメリットを感じられなかったため、採用しませんでした。
下のパターンは、単純に見づらいので採用しませんでした。
実際のソースコードでは、さらに多くの機能名が含まれるため、この構成だと設計書を探すのが大変になるのが容易に想像できました。
構成図やデータベース設計など、機能をまたぐものはdocsディレクトリにまとめました。
本当は、共通的なディレクトリを作るとコンフリクトが起きやすくなるので避けたかったのですが、現実問題データベース設計などは機能ごとに独立させるのは無理があるので、許容しました。
この構成における設計書で書くもの
この構成における設計書で書くものは以下の通りです。
- 機能の概要
- 何をする機能か
- 大まかな処理の流れ
- 入出力内容
- パラメータ
- 出力するファイル・データのフォーマットなど
- 使用方法／テスト方法
これらをMarkdownで表現できる形で書いていきます。
この構成を適用しているのはバックエンドのため、いわゆる画面イメージは含めていません。また、フローチャートやシーケンス図も入れていません。
それらが不要になるほど、個々の機能を小さくすることを重視しており、図示が必要ならdraw.ioなどで作成してdocsディレクトリに置くという形にしています。
メリットとデメリット
メリットの一つはコロケーションの思想通り、ソースコードと設計書が近いのでとても探しやすいことです。
特に説明しなくても、開発者が簡単にソースコードと設計書を行き来できるため、効率的です。
他のメリットとしては、ディレクトリ構成に進捗が如実に現れること、プルリクエストを追うだけで進捗が把握できることです。
この構成で開発が始まると、以下のように進行します。
- まず機能名のディレクトリができる
- 次に機能名のディレクトリ配下に設計書ができる
- 設計書のプルリクエストができて、マージされる
- 次にソースコードができる
- ソースコードのプルリクエストができて、マージされる
機能のディレクトリに設計書だけあれば、それは設計完了ではあるが実装はまだと言えます。
また、設計書もソースコードもレビュー依頼がプルリクエストに集中するので追うものが減り効率があがります。
現実的には、管理者が追うべきものはプルリクエスト以外にもIssueなどがありますが、実装に関することが追いやすいのは良いことだと思います。
反対に、デメリットとしてはディレクトリ構成を工夫しないとこの構成は採用しづらいことが挙げられます。
もう一つのデメリットとしては、レビュー専任の人にとっては必ずしも探しやすい構成とはいえないことです。
そもそもGitリポジトリを見ない人がいる場合はこの構成は見送るべきかもしれません。
まとめ
以上、バックエンドで設計書のコロケーションをやってみたというお話でした。
感想としては、開発者しか見ないドキュメントはGitリポジトリに入れ、機能ごとにソースコードと設計書をまとめると、確かに探しやすくて良いと感じました。
同時に開発者で完結しないドキュメントは、別の媒体で管理した方がよいでしょう。
本記事で書いたことが誰かの参考になれば幸いです。