データベースのストレージエンジンを、速さと互換性を崩さずに直す

## エラーと並行処理を正しく扱う、読みやすいコードを書く 意味のある名前を使い、明白でない不変条件にはコメントを添えて、明快で自己説明的なコードを書く。 わずかな高速化しか得られない巧妙な手法より、読みやすい制御フローを優先する。 リポジトリのフォーマッター、命名規則、構造パターンに従う。 プロジェクト標準のステータス型またはエラー型を一貫して使う。 失敗した操作を特定できるだけの文脈を付けて障害を伝播させる。 エラーや未確認のステータス値を暗黙のうちに破棄してはならない。 本番経路で回復可能な障害にアサーションを使わない。 不正な入力、リソース枯渇、I/O障害、破損、部分的な進行を網羅する。 キー順序、スナップショットの可視性、耐久性、復旧動作などのデータベース意味論を保つ。 同期に関する前提は、それによって保護されるデータの近くに記載する。 ロック、アトミック操作、メモリ順序、競合リスク、デッドロックリスクをまとめてレビューする。 成功、エラー、キャンセル、シャットダウンの各経路でリソースの後始末を明示する。 コメントは、特定の呼び出し元における現在の理由ではなく、局所的な契約に焦点を当てる。 共有抽象化の責務が安定して一貫している場合は、重複するロジックを集約する。 障害経路と並行動作をテストするまで、正当性に関わる変更をマージ可能と判定してはならない。 ## 実行される回数に合わせて、ベンチマークで確かめて速くする ストレージエンジンの作業では、性能を意識することを必須要件として扱う。 最初から妥当なアルゴリズムとデータ構造を選びつつ、細かな最適化より先に正当性を確立する。 影響を受けるコードを実行頻度で分類する。 - ホットパスでは、頻繁な操作を通じて割り当て、コピー、分岐、キャッシュミスのすべてが累積する。 - ウォームパスでは、明快さと速度の均衡を測定に基づいて取る必要がある。 - コールドパスでは、プロファイリングで重大なコストが判明しない限り、保守性を優先する。 性能に関する主張は、ベンチマークとプロファイリングのデータで裏付ける。 適切な基準値と比較し、ワークロード、構成、ばらつきを報告する。 正当な理由がある場合は、再利用、事前割り当て、アリーナ、メモリプールによってホットパスの動的割り当てを減らす。 不要なコピーより、ムーブ、ビュー、参照、インプレース操作を優先する。 局所性を高めるようにデータとアクセスパターンを配置し、偽共有を避ける。 不変の処理をループ外へ移し、反復操作をまとめ、予測しにくい分岐を減らす。 分岐予測ヒントは、本当にまれな場合やコストの高い場合だけに使い、一般的な構成には使わない。 明示的な組み込み命令へ進む前に、適切なデータ配置によってコンパイラのベクトル化を有効にする。 明示的なSIMDは、対応し、測定済みで、保守可能な箇所にだけ使う。 低いオーバーヘッドを保ちながら漏れを防ぐため、RAIIと明確な所有権を適用する。 再現可能な利点のない複雑な最適化を残してはならない。 ## 1つの役目だけのオプションで、互換性を保つAPIを作る 高水準の方針は、呼び出し元または方針層に置く。 下位層からは、正確で再利用可能な仕組みを提供する。 汎用コードを、特定の呼び出し元の識別情報や理由に依存させてはならない。 各フラグまたはパラメーターに、一貫した動作を一つだけ持たせる。 所有権、キャッシュ、I/Oモード、プリフェッチを一つに束ねるブール値は、明示的なフィールドまたはオプションオブジェクトに置き換える。 キャッシュハンドルやリーダー状態など、実装上の付随的な詳細から方針を推測してはならない。 アサーション、より限定されたインターフェース、明確な名前を使い、契約を強制可能にする。 新しいAPIを、既存の命名、パラメーター順、戻り値型、エラー処理と一貫させる。 適切な箇所では、固定幅整数型やスコープ付き列挙型を含む型安全なオプションを使う。 オプション値を検証し、明確なエラーを返す。 動的な構成変更をスレッドセーフにし、いつ有効になるかを確認する。 破壊的変更に例外的な正当性がない限り、ソース互換性とバイナリ互換性を保つ。 公開バイナリインターフェースを提供する場合は、レイアウト、シンボル、呼び出し規約をレビューする。 文書化された複数リリースにわたる手順で非推奨化し、移行案内を提供する。 公開APIについて、使い方、パラメーターの意味、スレッド安全性の規則、性能コスト、互換性の注意点を記載する。 第三者実装の型を公開APIから露出させてはならない。 ## 先行書き込みログなど、壊れると危ない部分ほど深くレビューする 先行書き込みログ、メモリテーブル、コンパクション、復旧、その他のデータベース中核経路には最も深いレビューを適用する。 さまざまな構成、コンパクション方式、障害、並行ワークロードの下で中核部分の変更をテストする。 コンパクションが設定上限を守り、空または単一ファイルの場合を処理できることを確認する。 公開ヘッダーを互換性への影響が最も大きい対象として扱う。 永続テーブル形式とブロック形式を長期的なデータ契約として扱う。 圧縮方式、ブロックサイズ、破損事例、互換性境界を変えてチェックサムを検証する。 イテレーターのシーク、次、前、消去、端点の意味論をテストする。 キャッシュキーを一意に保ち、プリフェッチがリソース上限を守ることを確認する。 ホットパスで動作し得るテーブル、キャッシュ、ユーティリティーの変更をベンチマークする。 キャッシュの同期、メモリ所有権、エビクション方針を明示する。 任意機能のユーティリティーをデータベース内部から分離する。 オプションについて、型安全性、検証、非推奨化、スレッドセーフな動的更新を確認する。 内部ユーティリティーでは、オーバーフロー、アンダーフロー、不正な入力、アサーション契約をテストする。 高リスクな形式、復旧、コンパクション、キャッシュの変更を、単体、統合、ストレス、ベンチマークの証拠なしに承認してはならない。 ## 全部のビルドシステムをそろえ、対応する全OSでビルドを通す ソースファイルを追加または削除する場合は、対応するすべてのビルドシステムを保守する。 最初に正本のソースマニフェストを更新し、承認済みの生成ツールで派生ビルドファイルを再生成する。 生成された内部ビルドファイルを手作業で編集してはならない。 影響を受ける参照を、すべてのビルド定義、言語、文書、実装から検索する。 リソース上限の範囲内で、ホストのCPU数を並列ビルドに使用する。 異なるビルドモード間で互換性のないオブジェクトファイルが再利用されないようにする。 手動ビルドでは、構成変更時に自動クリーンするビルドシステムの仕組みを有効にする。 プロジェクトのOS、コンパイラ、標準ライブラリ、サニタイザー、ビルドモードの組み合わせをサポートする。 設定されている場合は、Linux、macOS、Windows、ネイティブおよびクロスコンパイラ、リリースビルド、サニタイザー、ユニティビルド、言語バインディングを想定する。 プラットフォームAPIの直接利用より、プロジェクトの移植性抽象化を優先する。 避けられないプラットフォーム固有のヘッダー、呼び出し、属性、組み込み機能にはガードを設ける。 推移的インクルードに依存せず、必要な標準ヘッダーをすべて直接インクルードする。 それがプロジェクトの制約である場合、本番用とストレステスト用のバイナリが実行時型情報なしでビルドできることを確認する。 実行時ダウンキャストはテストだけに限定し、それ以外ではプロジェクトの検査付き静的キャスト補助機能を使う。 未対応の文字やその他のCI非互換コンテンツを拒否するソース検査を実行する。 リポジトリで求められる場合は、ソースコメントと文字列にASCIIの句読点を使う。 ## スリープに頼らず、失敗を再現できるテストを書く リスクに応じてテストの深さを決める。分離した動作には単体テスト、相互作用には統合テスト、並行性と性能にはストレステストを使う。 境界、エラー経路、復旧、プラットフォーム差、回帰事例を網羅する。 入力が異なっても検証する契約が共通する場合は、テーブル駆動のテストケースを使う。 反復する構築、往復変換、アサーション列には補助関数を抽出する。 決定論的な境界事例とランダム化した網羅範囲を分ける。 有用な範囲をより広く網羅できる場合は、パラメーター積の全探索よりランダムサンプリングを優先する。 プロジェクト標準の乱数源を使い、障害を再現できるようにシード値を表示する。 並行イベントを待つためにスリープしてはならない。 同期点または明示的なシグナルを使ってスレッドの進行を制御する。 個々の単体テストの実行時間を、定義済みのタイムアウトで制限する。 少数の対象テストは直列で実行し、大規模なテスト群は並列テストハーネスで実行する。 強制的なコンテキスト切り替えの下で、新しい並行性テストを繰り返しストレス実行する。 CIだけで発生する不安定な失敗を、プロジェクト専用の再現ツールで調査する。 パス、API、コンパイラ、ビルドフラグの影響を受けるすべての対応プラットフォームをテストする。 テスト失敗時に、原因となった構成を再現するための状態が十分報告されるようにする。 新しい構成オプションと性能機能を、ストレステストとベンチマークの対象に加える。 提出前に、更新したテストの重複と意図しない共有状態をレビューする。 ## ライセンスヘッダーを付け、文書とリリースノートを合わせる 新しいソースファイルには、リポジトリで必須のライセンスヘッダーを付ける。 派生ファイルでは、プロジェクトのヘッダーに加えて上流の著作権表示を保持する。 各ソース言語に適したコメント接頭辞を使う。 必須のデュアルライセンス表記を一般的な権利表明に置き換えてはならない。 変更後に自動整形を実行し、その差分を確認する。 依存関係保守ツールを実行し、無関係なマニフェスト変更を受け入れない。 機能を追加する際は、ホットパスの性能低下を招かない範囲で有用な指標を検討する。 性能関連機能を標準のベンチマークツールから利用可能にする。 リリースノートは短く外部向けにし、利用者から見える動作に焦点を当てる。 構成要素の設計を、サブシステムの索引と専用の章に記載する。 必要な場合は、生成サイトや投稿が有効な著者メタデータを参照するようにする。 新しいAPI、オプション、非推奨化では、リポジトリ専用の手順に従う。 非推奨の公開面を削除する前に、移行案内を更新する。 実装、ビルドメタデータ、テスト、文書、リリースノートの同期を保つ。 新しいソースファイルを、一つのビルドシステムから参照できる一方で別のビルドシステムには存在しない状態にしてはならない。 ## クリーンビルドとテストを通してから、変更を承認する 正当性、テスト、性能、互換性、契約境界、スタイル、文書をそれぞれ独立した判定項目としてレビューする。 性能に関わる変更にはベンチマーク結果を必須とする。 新しい並行動作または構成可能な動作には、ストレステストの網羅を必須とする。 対象を絞った検査に合格した後、完全なクリーンビルドとテストのターゲットを実行する。 無視されたエラー結果を検出する、より厳格なステータス検査用ビルドを実行する。 変更されたビルドフラグが古いオブジェクトを再利用できないよう、自動クリーンモードを使う。 ビルドシステムの機械可読な進捗情報を通じて、長時間のテスト実行を監視する。 段階、完了した作業、作業総量、失敗、割合、上限を設けた失敗詳細を追跡する。 アサーション失敗を、クラッシュ、シグナル、タイムアウト、基盤エラーと区別する。 報告する証拠とともに、ベンチマークのパラメーターとテスト構成を保持する。 測定用のベンチマークはリリースモードでビルドする。 クラッシュを診断するときはデバッグビルドに切り替え、再測定の前にクリーンな状態で再ビルドする。 影響範囲に必要な整形、ソース、ビルド、テスト、サニタイザー、プラットフォームの検査を実行する。 レビュー修正後、直接影響を受ける判定項目を再実行する。 一部の一致が可能性の低いものに見えても、リポジトリ全体の一貫性検索を狭めてはならない。 コード、契約、テスト、ビルドメタデータ、文書、測定済みの証拠が一致する場合にのみ承認する。