■ 1. 問題提起: 実装詳細と設計判断の境界
- ボタンの「押下」という表現が曖昧であったため、
mousedownイベントで実装されトラブルになった事例を起点とする- 実装方法によって守られる性質が変わる場合、その選択は単なる実装詳細ではなく、設計時点でレビューできる形にすべきである
■ 2. mousedown と click の違い
mousedown:
- ボタンを押し込んだ瞬間に処理が開始される
- その後ポインターをボタン外へ移動しても処理は取り消せない
- ドラッグ開始など、押し込んだ時点での反応が適切なケースに向く
click:
- クリック操作が成立した時点で処理が実行される
- 押し込み後にポインターをボタン外へ移動して解放した場合は処理が開始されない
- 購入・送信・削除など取り消しにくい操作に適する
- どちらが常に正しいかではなく、選択によって振る舞いが変わる以上、それは設計上の判断である
■ 3. 設計書への記述方針
- 意図が明確な場合:
- 外部から観測できる振る舞いと想定する実装の両方を記述する
- 例: 「ボタン上でポインターが押し込まれた時点で処理を開始する。ポインターを外へ移動して解放しても処理は取り消さない」
- 実装方法が未確定な場合:
- 外部から観測できる振る舞いや守るべき性質を記述する
- 共通の目的:
- レビューに参加する人が同じ振る舞いを想定できる粒度まで具体化し、認識の齟齬を減らす
- 「押下」とのみ記述するのは、設計上の判断を文書に落とせていない状態である
■ 4. Design Doc に書くべき内容
- 「何を実装するか」だけでなく、以下を明示する:
- 何を守るのか
- 何を許容するのか
- なぜその選択をしたのか
- 別の選択肢を採らなかった理由
- 目的はすべての実装方法を固定することではなく、暗黙の前提をなくしてレビューの対象にすること
- 冪等性の例:
- 「冪等にする」と書くだけでは何について冪等性を保証するか不明である
- 重複を許容する場合は何が重複し得るか、なぜ許容できるか、重複時の扱いを記述する
- 重複を許容しない場合はどの状態遷移や副作用について重複を防ぐか、守るべき条件を記述する
- 設計判断が文書に現れていない場合、レビュアーは正常系の構成しか確認できない
■ 5. 設計におけるトレードオフ
- 設計とは、制約の中で何を守り、何を諦めるかを決めることである
- すべてを守ろうとすれば実装・運用が複雑になり、開発速度・性能・可用性など別のものを失う
- 何を保証し、何を許容し、そのために何を諦めたかを明確にする必要がある
- Design Doc は、判断と想定される失敗を暗黙の前提にせず、レビュー参加者が同じ前提に立ち設計の妥当性を確認できる形にするための文書である