rust-best-practices

name	rust-best-practices
description	Rust best practices guideline

このスキルを使うべきとき

このスキルは、Rustを記述する時に常に参照し、本文書に記述されたRustの ベストプラクティスおよびユーザのコーディングスタイルに従って開発を 進めるためのものである。

instruction

• 基本的には一般のRustのベストプラクティスに従うこと。
• 手続き的な処理の記述を避け、イテレータや標準の関数を用いた記述を心がけること。ただし、その記述が実行効率を損なう場合はこの限りではない。
• #[allow(...)] の利用には慎重になること。また、 #![feature(...)] といった、 unstable 機能の利用は、必ず確認を取ること。
• 新しいマクロの定義は慎重になること。マクロの多用は可読性を下げるが、その方が良い場合もある。
• unsafe や Box::leak 、 forget は一般に使用するべきではない。多少の最適化のために使うのは推奨しない。もし使用する場合、確認を取ること。

API設計

• 綺麗なAPI設計を心がけ、外部のユーザが使えるように、CLI部分以外は src/lib.rs として実装すること。
• ディレクトリ下に mod.rs を作らず、 [module_name].rs を作成し、子のディレクトリ以下にモジュールの各ファイルを作成すること。
• APIの公開、非公開については熟慮してください。なんでも公開にせず、また pub(crate) などの利用にも慎重になること。
• 単一のバイナリクレートは、 src/main.rs に実装すること。ただし、複数のバイナリクレートがある場合には src/bin/ 以下にそれぞれ作成すること。

依存クレート

• 依存関係追加時は、必ず crates.io を参照し、最新のバージョンを用いなくてはならない。
• クレートのタイプに応じて適切な粒度のバージョン指定を心がけること。
• 依存クレートに関するドキュメントは、 docs.rs かダウンロードしたクレートのソースコードを確認するのが最も良い。

型の設計

• 特定用途の値には、専用の型を作成する new type pattern を採用すること。
• 定義した型に無駄に多くのトレイトを実装する必要はないが、Clone, Debug などを #[derive(...)] を用いて実装してください。可能な場合は Copy, Eq, Default なども実装すると良い。
• 関数の引数、返り値の型は適切にトレイトなどを用い、また新しく定義する型もジェネリックな設計を心がけること。
• 重複したコードを避けるため、トレイトを用いて共通化を行うこと。

コード品質

• コード品質の維持にClippyを用いる。作業の区切りの際に、指示を待たずに cargo clippy --all-targets を実行すること。
• すべて書き終えたら、 cargo fmt をしてフォーマットを整えること。

特定のクレートに関する規約

• serdeクレートを用いる場合は、公開する型では Serialize, Deserialize の両方を実装した方がいい場合が多くある。また、 #[serde(rename_all = "snake_case")] や、 #[serde(tag = "...")] などを積極的に活用すること。