pit-of-success

成功しやすい設計

誤用を難しくし、自然な呼び出しが正しく動くようにします。

手順

1. 使用されている公開境界を見つけます。エクスポートされた関数、フックの戻り値、セッター、コンポーネントのプロパティ、ルートの本文、スキーマ、コマンドなどです。次に、その境界を呼び出すすべての箇所を検索します。将来のメンテナーが自然に書く呼び出し方を把握できたら完了です。
2. 誤用しやすい箇所がないか確認します。「隠れたヘルパーや慣習を知らない人が、自然な方法で操作した場合に動作が壊れるか？」と問いかけてください。例：setSelection(null) は、製品で通常想定されるクリア動作を意味するべきです。スキーマは UI で望まない状態を拒否するべきです。プロパティは、兄弟プロパティとの正しい組み合わせを要求するべきではありません。
3. 不変条件を境界に移します。次の順で検討してください。
   • 既存の API で安全な操作ができるようにする。
   • 不正な状態を表現できないように、型またはスキーマを絞り込む。
   • 危険な経路が明示されるように、API の名前を変更するか分割する。
   • そのうえで、すべての自然な呼び出し元が使う場合に限り、ヘルパーを追加する。
4. 回避策と重複した意味を取り除きます。ローカルのラッパー、並行するヘルパー名、落とし穴を説明するコメントを、境界にある一つの共有実装に置き換えます。
5. 一つのチェックで落とし穴が塞がれたことを証明します。自然な呼び出しで動作が保たれることを示す、焦点を絞ったテストまたは型／スキーマのアサーションを行い、さらに grep で、古い落とし穴を使う呼び出し元が残っていないことを確認します。

ルール

• 指定された呼び出し箇所だけを修正しないでください。境界が間違っているなら、境界を修正します。
• 呼び出し元が生の API を引き続き呼び出せる場合は、「まずこのヘルパーを呼ぶのを忘れないでください」に頼らないでください。
• 誤用を不可能または明白にする代わりに、コメントを追加しないでください。
• 差分は地味に保ちます。不変条件は一つ、所有者は一つ、先回りした抽象化は加えません。
• 互換性の都合で境界を変更できない場合は、危険な API にその旨が分かる名前を付け、その隣に安全なデフォルト API を用意します。