ds-principles

エンジニアリングの原則

トリガーに該当したら、そのルールを適用してください。判断を変えた原則を明示してください。

設計

1. まず削り、追加は少しだけ。 動作しなくなったコードや古くなったチェックを先に削除し、そのうえで動作する最短の差分にします。利用箇所が一つしかない抽象化は作りません。差分の規模を決めるときや、レイヤーを追加したくなったときに適用します。
2. まずデータの形を決める。 ロジックより先に、中心となる型や構造を選びます。新しいロジックを書く前に適用します。
3. ドメインをモデル化する。 状態は、あちこちに条件分岐として散らすのではなく、判別共用体、ステートマシン、ルックアップテーブルなどの一つの構造にまとめます。コードの分岐が多いときや、複数のファイルで同じ形が繰り返されるときに適用します。
4. 新しい要件に合わせて再設計する。 新しい要件が最初から存在していたかのように設計を整えます。追加によって設計に無理が生じるときに適用します。
5. 読み手の負担を抑える。 呼び出し元が一つだけのラッパーはインライン化し、可変状態のスコープを小さくします。コードを追いにくいときに適用します。
6. 境界でガードする。 CLI、設定、ネットワーク、ファイル、外部 API など、入力が入る場所で検証します。内部では型を信頼し、コアロジックは純粋に保ちます。検証やエラー処理を追加するときに適用します。
7. ステップを冪等にする。 クラッシュ後も含め、ステップを再実行しても同じ状態に到達するようにします。コマンド、セットアップ、再試行に適用します。
8. 書き込み元を共有しない。 ロックを使う前に、並行する各アクターにそれぞれのファイル、ブランチ、またはキーを割り当てます。並行作業が共有状態に触れるときに適用します。
9. 移行してから削除する。 すべての呼び出し元を移行し、同じ変更で古い API を削除します。つなぎの仕組みは設けません。API の置き換えや段階的な書き換えに適用します。
10. 選択肢を比較する。 前例のない設計では、2〜3 案を簡単に描き出します。機能を少なく、洗練されたものにすることを優先します。目新しいアーキテクチャ、UX、スコープを選ぶときに適用します。

デバッグと検証

11. 根本原因を直す。 状態が最初に誤った場所を修正します。ガードで直せるのは、正当な状態だけです。デバッグ時に適用します。
12. 前提を疑う。 同じ前提に基づく修正が2回失敗したら、その前提を書き出し、直接検証します。3回目を試す前に適用します。
13. 動作を証明する。 代替手段ではなく、実際のものを実行し、実際の出力を確認します。完了を宣言する前に適用します。
14. 検証可能な単位にする。 各ステップが成功したチェックで終わるように作業を分割します。一括処理、移行、積み重ねたコミットに適用します。
15. 振る舞いをテストする。 呼び出し元から観測できることを検証し、リファクタリング後もテストが有効であるようにします。テストを書くときや維持するときに適用します。
16. 数値の意味を説明する。 測定を制限しているものを特定し、正しい作業を測定していることを確認します。ベンチマークや評価スコアに適用します。
17. ツールを作る。 大量の作業や繰り返し作業は、再実行できるようスクリプト化します。大規模な編集やチェックに適用します。

プロセス

18. コンテキストを守る。 ダンプではなく要約を保ちます。大量の読み取りはサブエージェントに任せます。出力やファイルが大きいときに適用します。
19. 人の返答待ちで止まらない。 元に戻せる作業なら進めて、結果を示します。「確認すべきか」と尋ねたくなったときに適用します。
20. 繰り返し得た教訓を仕組みにする。 同じ指摘を2回受けたら、リンター、テスト、またはスクリプトにします。ミスが繰り返されるときに適用します。
21. コメントには理由を書く。 外部の制約や公開 API の契約など、コードから読み取れない理由がある場合に限りコメントを残します。説明に終始するコメントや使われていないコードは削除します。意外に見える理由をコメントで説明する必要があるコードは修正します。コードを書くときやレビューするときに適用します。

型

• 不正な状態を表現できないようにします。省略可能なフィールドを並べたオブジェクトではなく、判別共用体を使います。
• 外部データは境界で一度だけ解析し、名前付きの型にします。内部ではその型を信頼します。
• 信頼できない入力には unknown を使います。any は使いません。検証前に as キャストを使ってはいけません。
• 手書きのガードではなく、スキーマから型を導出します。
• default 分岐に never チェックを追加し、新しいバリアントが追加されたときにビルドが失敗するようにします。
• ユーザー ID と注文 ID のように、混同してはならないプリミティブ型にはブランドを付けます。