rust-best-practices

Rust のベストプラクティス

既存のクレート設計、エディション、rust-toolchain.toml、および Cargo.toml の rust-version（MSRV）に従ってください。参考例では新しい機能が使われている場合があります。採用する前にサポート状況を確認してください。例に従うためだけにツールチェーンをアップグレードしたり、クレートを追加したりしないでください。

変更する Rust のテーマに関するリファレンスを読んでください。局所的な編集に、すべてのカテゴリ、新しいテストフレームワーク、ワークスペース全体の監査が必要なわけではありません。

トピック	リファレンス	読み込むタイミング
コーディングスタイル	references/coding-style.md	命名、インポート、イテレーター、コメント、文字列の扱い、マクロ
エラー処理	references/error-handling.md	Result、Option、?、thiserror、anyhow、カスタムエラー、非同期エラー
所有権とポインター	references/ownership-and-pointers.md	ライフタイム、借用、スマートポインター、Pin、Cow、内部可変性
トレイトとジェネリクス	references/traits-and-generics.md	トレイト設計、ディスパッチ、GAT、シールドトレイト、型状態パターン
非同期処理と並行処理	references/async-and-concurrency.md	Tokio、チャネル、ストリーム、シャットダウン、ランタイム設定、非同期トレイト
同期処理と並行処理	references/concurrency-sync.md	アトミック、Mutex、RwLock、ロック順序、Send/Sync、メモリ順序
テスト	references/testing.md	ユニット／統合／ドキュメントテスト、スナップショット、proptest、mockall、ベンチマーク、ファズ
パフォーマンス	references/performance.md	プロファイリング、フレームグラフ、クローン、スタックとヒープ、イテレーター、アロケーション
Clippy とリンティング	references/clippy-and-linting.md	Clippy の設定、主要な lint、ワークスペースの設定、#[expect] と #[allow] の使い分け
ドキュメント	references/documentation.md	ドキュメントコメント、rustdoc、ドキュメント lint、カバレッジのチェックリスト

エンジニアリングの基本基準

• 所有権の借用または移譲は意図的に行い、独立した所有権が必要な場合はクローンしてください。数値的なサイズ規則や、あらゆるアロケーションを避けることよりも、明確な所有権を優先してください。
• 失敗する可能性がある処理は Result で扱い、有用なエラーコンテキストを保持してください。panic／アサーションはプログラマーの不変条件に違反した場合に限定し、外部入力は回復可能なエラーで検証してください。
• エラー型、ディスパッチ、依存関係は、既存の公開契約に合わせてください。thiserror、anyhow、Tokio、サードパーティ製の同期クレートは選択肢であり、必須の追加ではありません。
• ロックを保持する期間を短くし、ロック順序を維持してください。また、キャンセル、シャットダウン、スポーンしたタスクの所有権について検討してください。同期ロックを .await をまたいで保持しないでください。
• Send／Sync の境界とアトミックの順序は、正しさに関わる性質として扱ってください。有効な同期の根拠がある場合に限り、より弱い順序を選択してください。パフォーマンス向上を目的に書き換える前にベンチマークを実施してください。
• 動作テストは、その不変条件を担保するテストスイートに追加してください。型レベル、プロパティ、ファズ、スナップショット、ベンチマークの各テストは、契約やリスクに応じて追加してください。
• リポジトリで必須とされている範囲のフォーマット、lint、テストのコマンドを実行し、有効な実行結果は再利用してください。ワークスペース全体／全フィーチャーの実行とドキュメントカバレッジのルールには、プロジェクトのポリシーが適用されます。クレートが実際にサポートしているフィーチャーの組み合わせを確認してください。