皆さんこんにちは。
ユニバーサルゲーム事業部でサーバーエンジニアをやっております、田口です。
入社して結構な月日が経ち、最近では大規模開発の設計をやる機会が非常に増えたのですが今までの設計のやり方だと分かりづらかったり、レビューしづらかったりと苦しい状況になってきたため思い切って設計専用リポジトリを作ったら色々解決した！という話をさせて頂きます。
元々どのように設計を書いていたか
GitHubのIssueに設計を直接書いてました。
設計で書く内容としては以下があり、これらをIssueのコメントで1つずつ記載してました。
- 概要
- DB設計
- APIインターフェース設計
- 機能設計
- ログ設計
そしてレビューに出した後、さらにIssueのコメントにレビューを書き、やりとりをしていくわけですが・・・。
これらを続けていくと以下のような状態になってました。
- レビューコメントがどんどん増えて長くなるので、Issueを開くのに時間がかかるようになってきた
- Issueコメントが増え、設計とコメントが混ざっている状態になってしまっていた
上記の状態になってしまい、設計を書く側・レビューする側ともに分かりづらくなってしまい、設計レビューにおけるボトルネックになってしまってました。
特に直近は開発規模の大きいものを設計することが多かったため、コメント量はかなり膨大になっていってました。
何をしたのか
上記を解決するため、設計専用のリポジトリを作成しました。
新規作成、もしくは修正する機能ごとにディレクトリを分け、その中に以下のように各設計をマークダウンファイルで管理するようにしました。
ディレクトリ(プロジェクト毎)
├─ 概要.md
├─ DB設計.md
├─ 機能設計.md
├─ APIインターフェース設計.md
├─ エラー設計.md
└─ ログ設計.md上記のテンプレートを設定し、レビューの際は作業ブランチを切ってmasterブランチをマージ先としてPull Requestを作成するようにしました。
また、指摘したい箇所にコメントし、解決したらResolveに変更する運用を行うことで、指摘コメントがどこの箇所に対するものなのか分かるようにしてやってみました。
導入してみてここが変わった！
設計を書く人
- 書きやすくなった、修正が楽になった
エディターを使って書けるので拡張機能入れておけばおかしい日本語やタイプミスにもすぐ気付けるようになりました。 - レビューが完了したか分かりやすくなった
Approveという形で完了したかどうかが分かりやすくなりました。
Issueに書いていた時は、スタンプか質問が来なくなったらOKかなというざっくりとしたフローでやってました。
なので目に見えてOKかどうかが分かるようになったのは非常に大きいですね。 - クライアントエンジニアへの情報共有がやりやすくなった
APIインターフェースやエラーコードの設計をそれぞれ別ファイルとしたので探しやすくなりました。
上記2つの設計はクライアントエンジニアに共有する内容となるので、ディレクトリ配下にあるのを見てもらえばOKになったのはお互いに楽になったかなと思います。
Issueだと指摘コメントが残っていたので、それがPull Request内で収まったことにより可視性・可読性が上がったのも良い点です。
設計をレビューする人
- レビューがしやすくなった
話題ごとにPull Requestのコメントを付けれるので指摘箇所が分かりやすくなりました。
ちなみにエディターで開けるようになったので、ブランチをチェックアウトしてきて文章チェックやタイプミスの確認まで楽にできるようになりました。 - 実装時のレビューにも使用しやすくなった
実装後のコードレビューで設計と合っているかの確認をするのですが、その際に情報を拾いやすくなりました。
まとめ
設計書の作成方法を変えることで、可視性・可読性が大幅に上がりすごく使いやすくなりました。
また、これを機にER図を作って設計に導入する人がいたり、Mermaid記法でシーケンス図を作ってみたりと、さらに設計の質を上げられるようなアクションが少しずつ出始めたのも良い傾向だなと感じてます。
困っている人はぜひ一度試してみてください。
それでは良い設計ライフを！