データ処理ライブラリを、見つけやすいAPIと実データのテスト付きで作る

## 複雑な元データを、シンプルなオブジェクトの裏に隠す 重要な機能を隠すことなく、元データ形式の複雑さを直感的なドメインオブジェクトの背後に収める。一般的な操作は直接実行できるようにし、専門的な解析、レポート作成、調査の機能は、利用者が必要とした時に段階的に提示する。 書く前に読む。コードを変更する前に、既存の抽象化、命名パターン、モジュール境界、周辺のテストを調べる。具体的な非互換性のために新しいパターンが必要な場合を除き、既存の設計を拡張する。 ## 編集の前に、どのモジュールが何を受け持つかを地図にする 利用者の目的から担当モジュールと主要なドメインクラスへたどれる簡潔な案内図を維持する。記録の検索、エンティティの読み込み、構造化データの解析、明細の構築、注記の参照、文書の展開、型付きレポートの作成に使う公開エントリポイントを含める。 編集前に、代表的なデータフローを始点から終点まで追う。要求が公開エントリポイントから取得、解析、型付きオブジェクト、明細、注記、レポート、文書抽出へ進む過程を確認する。各変換をどの層が担当するか、利用者が裏付けとなる詳細へどこから掘り下げるべきかを確かめる。 案内図を使って、責任を担う最小のモジュールを選ぶ。別の層がすでにその責任を持つ場合、都合のよいファイルへ動作を置いてはならない。 ## 大きなファイルは少しずつ読み、直す所を狭くする 30 KBを超えるモジュールは、ひとまとまりとして読んだり書き直したりせず、複数の局所的な文脈として扱う。対象のシンボルを検索し、それを含むクラスまたは関数を調べてから、不変条件と呼び出し元を理解するために必要な範囲の周辺コードを読む。 大きなファイルを変更する前に、関連するテスト、import、サブクラス、外部から参照される箇所を特定する。差分を狭く保ち、周辺の規約を維持し、機能変更を見えにくくする無関係な再整形や再構成を避ける。 ## 作業を課題管理ツールに記録し、状態を更新する プロジェクトの課題管理システムを、進行中の作業を残す正本として使う。未着手と進行中の項目を確認し、該当する課題を選び、実装前に進行中へ移す。新たに見つかった不具合やタスクはコメントやチャットだけに残さず、明確なタイトル、種類、優先度を付けて記録する。 範囲、阻害要因、結論が変わった時は同じ課題を更新する。必要な検証が完了するまでは閉じない。未着手、進行中、阻害中、完了という定義済みの状態を維持する。課題管理システムが5段階の優先度を使う場合は、`0`を最重要、`4`をバックログとして保ち、場当たり的なラベルを作らない。 ## ライブラリが文書の約束どおりに動くかを確かめる 検証では、内部コードが単に実行できるかではなく、ライブラリが文書で約束した内容を提供しているかを確認する。次の3つの原則を適用する。 1. 文書が仕様であるため、文書にあるすべての例を検証可能にする。 2. データの正確さは不可欠であるため、存在することだけでなく、具体的な期待値を検査で確認する。 3. APIは利用者が答えに到達できるものでなければならないため、利用者とエージェントが質問から適切なオブジェクト、メソッド、裏付けとなる根拠へたどれるようにする。 これらの原則を使い、機能設計、文書、テストケース、失敗時の動作を一体として評価する。 ## 新しい機能に、実データの値のテストと動く文書の例を付ける 新しいユーザー向け機能には、必ず次を含める。 - 独立して確認済みの実在する元記録の具体値を使った、正解データに基づくアサーションを1つ。 - 自動検証としても実行できる、文書化された例を1つ。 - 不正または欠落した入力が、空の値や無言の失敗ではなく有用なエラーを返すことを証明する無反応チェックを1つ。 - プロジェクトの案内、機能カタログ、エージェント向けガイダンスのいずれかに機能を掲載する、見つけやすさの更新を1つ。 正常系の実装が動作していても、これらの要素が1つでも欠けていれば、その機能は未完成である。 ## 速いローカルテストを先に、ネットワークのテストは1つずつ回す 高速なローカル検証、ネットワークを使う検証、回帰検証、カバレッジ報告には、それぞれ別のコマンドを用意する。まず関連する最小のローカル検査を実行し、焦点を絞った結果が合格した場合にだけ範囲を広げる。 外部サービスへ接続しない高速テストだけを並列実行する。ネットワーク検証は順番に実行し、サービスのレート制限を守る。検証対象の契約を隠さずに外部動作を高速かつ決定的にできる場合は、記録済みのレスポンスfixtureを使う。 回帰検証は、各ケースと原因となった不具合を結び付ける安定した名前で、専用領域に配置する。カバレッジは補助的な根拠として扱い、動作とデータに関するアサーションの代わりにはしない。 ## いろいろな元データで、正確な値と分かりやすいエラーを確かめる 正確なドメイン値、正規化された構造、意味のあるエラーメッセージを確認する。正確さが値そのものに依存する場合、結果が存在することだけを確認するアサーションでは不十分である。 使い慣れた1つの例だけに依存せず、組織、業種、形式、報告期間の異なる元記録を使う。不正な形式、不完全な入力、未対応の入力を明示的に試す。失敗時に実行可能な対処を示すメッセージが返り、空の結果へ何の通知もなく変化しないことを確認する。 外部データが必要な場合は、決定的なfixtureを維持し、その期待値をどのように確定したかを文書化する。上流の契約が変わった時は意図を持ってfixtureを更新し、失敗した検査を通すことだけを目的に更新してはならない。 ## バージョンと文書を、動くコードと食い違わないように保つ プロジェクトのバージョンは指定されたメタデータファイルから読み、無関係なモジュールへ重複して持たせない。リポジトリの案内、検証ガイダンス、公開例、機能カタログを、対応している動作と同期させる。 APIの経路が変わった時は、同じ作業項目の中で文書と実行可能な例を更新する。代替実装が正しくても、文書に記載された経路が動かなくなれば、ユーザー向け契約は破られている。