Rust API Guidelines Checklist

  • 命名 (クレートがRustの慣用的な命名規則に従っている)
    • 大文字・小文字の使い分けがRFC430に従っている (C-CASE)
    • 変換メソッドにas_, to_, into_を使っている (C-CONV)
    • Getterの名前がRustの規則に従っている (C-GETTER)
    • イテレータを生成するメソッドの名前がiter, iter_mut, into_iterとなっている (C-ITER)
    • イテレータの型名が、それを生成するメソッドと揃っている (C-ITER-TY)
    • Featureの名前に余計な単語が入っていない (C-FEATURE)
    • 命名時に単語を並べる順番が揃っている (C-WORD-ORDER)
  • 相互運用性 (クレートが他のクレートの機能とうまく連携できる)
    • 積極的に一般的なトレイトを型に実装している (C-COMMON-TRAITS)
      • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Display, Default
    • 変換に標準のトレイトFrom, AsRef, AsMutを用いている (C-CONV-TRAITS)
    • コレクションがFromIteratorとExtendを実装している (C-COLLECT)
    • データ構造がSerdeのSerializeとDeserializeを実装している (C-SERDE)
    • 型が可能な限りSend,Syncである (C-SEND-SYNC)
    • エラー型の意味が分かりやすく、行儀の良い実装となっている (C-GOOD-ERR)
    • バイナリ数値型がHex, Octal, Binaryによるフォーマットをサポートしている (C-NUM-FMT)
    • 読み書きを行うジェネリックな関数がR: ReadとW: Writeを値渡しで受け取っている (C-RW-VALUE)
  • マクロ (クレートが行儀のよいマクロを提供している)
    • 入力の構文から結果をイメージできるようになっている (C-EVOCATIVE)
    • アイテムを宣言するマクロが属性と衝突しない (C-MACRO-ATTR)
    • アイテムを宣言するマクロがアイテムを宣言できる場所のどこでも使える (C-ANYWHERE)
    • アイテムを宣言するマクロが可視性の指定をサポートしている (C-MACRO-VIS)
    • 型の指定が柔軟である (C-MACRO-TY)
  • ドキュメンテーション (クレートに十分なドキュメントが付けられている)
    • クレートレベルにコード例付きの詳細なドキュメントがある (C-CRATE-DOC)
    • 全てのアイテムにコード例が付いている (C-EXAMPLE)
    • コード例がtry!やunwrapではなく?を使っている (C-QUESTION-MARK)
    • 関数のドキュメントにエラー、パニック、安全性に関する事項が含まれている (C-FAILURE)
    • 文章に関係する項目へのリンクを含める (C-LINK)
    • Cargo.tomlが一般的なメタデータを全て含んでいる (C-METADATA)
      • authors, description, license, homepage, documentation, repository, readme, keywords, categories
    • 大きな変更が全てリリースノートに記載されている (C-RELNOTES)
    • 無用な実装詳細がRustdocに表示されていない (C-HIDDEN)
  • 予測性 (クレートを使い、見かけ通りに動作する読みやすいコードが書ける)
    • スマートポインタがinherentメソッドを持っていない (C-SMART-PTR)
    • 変換メソッドは最も関係の深い型に付ける (C-CONV-SPECIFIC)
    • 明確なレシーバを持つ関数はメソッドにする (C-METHOD)
    • 関数がoutパラメータを持たない (C-NO-OUT)
    • 奇妙な演算子オーバーロードを行っていない (C-OVERLOAD)
    • DerefとDerefMutを実装しているのはスマートポインタだけである (C-DEREF)
    • コンストラクタはスタティックなinherentメソッドである (C-CTOR)
  • 柔軟性 (クレートが実用的なユースケースを幅広くカバーしている)
    • 重複した処理を行わなくて済むように中間生成物を公開している (C-INTERMEDIATE)
    • 呼び出し側がデータをコピーするタイミングを決める (C-CALLER-CONTROL)
    • ジェネリクスを用いて関数の引数に対する制限を最小にしている (C-GENERIC)
    • トレイトオブジェクトとして有用なトレイトはオブジェクトセーフになっている (C-OBJECT)
  • 型安全性 (クレートが型システムを有効に活用している)
    • newtypeを使って静的に値を区別する (C-NEWTYPE)
    • boolやOptionの代わりに意味のある型を使う (C-CUSTOM-TYPE)
    • フラグの集合は、列挙型ではなくbitflagsで表す (C-BITFLAG)
    • 複雑な値の生成にはビルダーパターンを使う (C-BUILDER)
  • 信頼性 (クレートが間違ったことをしない)
    • 関数が引数を検証している (C-VALIDATE)
    • デストラクタが失敗しない (C-DTOR-FAIL)
    • ブロックする可能性のあるデストラクタには代替手段を用意する (C-DTOR-BLOCK)
  • デバッガビリティ (クレートが容易なデバッグを支援している)
  • 将来性 (クレートを、ユーザのコードを壊すことなく改善できる)
    • sealedトレイトを使って下流の実装を適切に防いでいる (C-SEALED)
    • 構造体のフィールドを適切にプライベートにする (C-STRUCT-PRIVATE)
    • newtypeを用いて実装詳細を隠蔽している (C-NEWTYPE-HIDE)
    • データ構造にderiveしたトレイトの境界を定義で繰り返さない (C-STRUCT-BOUNDS)
  • 必要事項 (ある状況下では重要な問題)
    • stableなクレートのパブリックな依存クレートがstableである (C-STABLE)
    • クレートとその依存先がpermissiveなライセンスの下にある (C-PERMISSIVE)