想定読者
- 設計しないでバグ生んでしまいがちのエンジニア
- 設計段階でレビューする文化がなくてまあまあバグ出ちゃう開発チームの一員
なぜ
これを考える前の状態が
- とにかくQA段階でのバグが多かった
- PRレビュー時の手戻りが多かった
- そもそも設計段階でのレビューがなかった
でした。このままじゃまずいよね、となり、
- まずは設計の段階でレビューをしましょう
- ただスピードを維持するために必要最低限な要素を簡単にまとめられるようなテンプレート欲しい
ってことで最低限これは書いてほしい項目を考えて運用してみました。四週間ほど運用してみた結果、
- 設計段階で考慮漏れに気づけた
- できる人がどこまで考えてやっているかがチームに共有できた
など一定効果があったので残しておきます。
基本設計
背景
- JIRAなどのチケットURL
- 機能概要
- そもそもなぜこれは必要なのか(これがないと誰がどう困るか)
【レビュー観点】
- チケットURLがあるか
- この機能は誰が/何のために必要か、が他人が見て理解できるか
- 「ユーザー」ではなくて最低限「ツイートをする人」くらいの粒度までは考えられているか
- try 書いている内容でわからなければ、この機能は例えばどんな時に使用するか聞いてみよう
用語
- 機能に関連する用語
- 〇〇とは？
- ××とは？
【レビュー観点】
- 関連する概念などの意味があっているか
- try 自分が意味わからなかった単語について設計者は知っているか質問してみよう
機能詳細
- 機能が完了したらできること
- 制約
【レビュー観点】
- 機能詳細に過不足はないか
- 例えば、〇〇の場合はツイートができない、などの制約に漏れはないか
- try 〇〇の場合はこれできる？みたいに聞いてみよう
詳細設計
実装イメージ
デザインのキャプチャがあれば貼る
影響範囲
- 既存の機能に影響があると思われる箇所を箇条書きする
- 懸念点とそれに対する対処方法を記述する
- 懸念はあったが、調査の結果影響ないことも記述する
【レビュー観点】
- 影響のある機能に漏れはないか
- web
- iOS/Android app
- など
TODO
- レビューしやすい単位を意識
- エンドポイント作成の時、データの取得/更新/削除はTODOを分ける
- 変更が大きくなりそうな場合によってはチケットを分割できているか
- 以下があればTODOごとに別途追記
- 判定/処理などに使用するデータ(新規/既存共に)
- 使用するライブラリ
- 考慮すべき点
【レビュー観点】
- TODOを見たら誰でも実装できるくらいのレベルまで落とし込めているか
- 関連するデータの記述はあるか
- 懸念とその対応策について言及できているか(設計者が対応策わからなければレビューで解消するため、レビュー時になくても可)
構成
- ディレクトリ構造
- ファイル名
- そのファイルの役割
【レビュー観点】
- ファイル名/ディレクトリ名はわかりやすいか
- ファイルの役割は明確か
- 既存のファイルで置き換えることができる箇所はないか
- try そのコンポーネントの責務は？と問いかけてみよう
終わりに
これで万事解決！なんてことはもちろんありませんが、設計レビューをやったほうがいいよね、と考えている誰か一人の参考になれば幸いです。