r-tidyverse-style

R パッケージコード向け Tidyverse スタイル

ユーザーから移行を依頼されていない限り、Tidyverse ガイドよりもパッケージで確立されている規約を優先してください。スタイルは正しさの証明にはなりません。整理の際も、公開されている動作は変更しないでください。

タスクの進め方

1. 範囲とモードを決めます。 レビューの場合は、編集せずに指定されたファイルまたは差分を確認してください。整理の場合は、合意した範囲だけを変更してください。新しいコードを書く場合は、規約を選ぶ前に近隣の R/ ファイル、テスト、スタイル設定を確認してください。関連する場合は、DESCRIPTION でサポート対象の R バージョンと依存関係を確認してください。
2. インターフェースを保護します。 コードの名前変更や再編成の前に、エクスポート、roxygen/NAMESPACE、S3/S4 メソッド、呼び出し元、テスト、ユーザーに表示される条件を確認してください。公開名、既定値、エラー、戻り値、依存関係、サポート対象の R バージョンの変更を、見た目だけの変更として扱わないでください。
3. 観察事項を分類します。 スタイル、保守性、潜在的なバグを区別してください。自動生成されたように見えるコードでは、コードをそのまま説明するコメント、重複したチェックやヘルパー、不要なラッパー、根拠の薄い tryCatch() フォールバック、動作と矛盾するドキュメントやテストを調査してください。削除する前に呼び出し元とテストで確認してください。コードの由来だけでは、何も証明されません。これらはレビューのヒューリスティックであり、Tidyverse のルールではありません。
4. リスクの低いものから変更します。 まず対象ファイルをフォーマットします。その後、冗長であることを確認できた箇所だけを簡素化し、意図や制約を説明するコメントは残してください。動作に影響する変更（パイプ変換、評価順序、制御フロー、公開名、エラーテキスト）は別途提案し、ユーザーがその範囲を許可した場合に限り、対象を絞ったテストとともに実施してください。依頼されていないリファクタリングをスタイルの見直しに持ち込まないでください。
5. 検証して報告します。 差分を確認し、必要に応じて関連する対象を絞ったテストや、より広範なパッケージチェックを実行してください。レビューのみの場合は、ファイル名と行番号を示し、修正案を添えて優先度順に指摘事項を報告してください。ファイルは変更しないでください。編集した場合は、変更内容、保留した内容、実際に実行したチェックを明記してください。スタイルの見直しを、正確性やセキュリティのレビューだと主張しないでください。

スタイルルール

以下のルールは、Tidyverse スタイルガイド（ソース、コミット 2aed77e 時点を参照）を選択的に言い換えたものです。これは公式の Tidyverse スキルではありません。リンクは出典であり、必読ではありません。ルールを明確にする必要がある場合や、ユーザーから確認を依頼された場合に限り、関連する章を開いてください。既定では、すべての章を読む必要はありません。

構文と名前

出典：構文。

• 説明的な snake_case の名前を優先します。値には名詞、関数には動詞を使います。ドットはS3メソッド名を見分けにくくする場合があります。ファイルやパッケージの外部で使われている名前を変更する前に、互換性を確認してください。
• インデントにはタブを使わず、スペースを2つ使います。カンマの後、通常の中置演算子の前後、名前付き引数の = の前後にはスペースを入れます。括弧の内側や $、::、:、^、単項の - の前後には入れません。tidy-evaluation演算子には例外があります。正規表現による編集より、構文を認識するフォーマット処理を優先してください。
• 代入には <-、名前付き引数には = を使います。セミコロンや、1行に複数の文を置くことは避けてください。
• 開き波括弧は行末に、閉じ波括弧は行頭に置き、else は直前の } の横に置きます。複数行にわたる分岐やループには波括弧を使います。意味を確認せずに if をベクトル化された ifelse() に置き換えたり、&／| を &&／|| に変更したりしないでください。
• 長い呼び出しの引数は、別々の行に一貫したインデントで記述します。読みやすい行の長さを目指してください（80文字は目安であり、厳格な上限ではありません）。
• 関連する文は視覚的にまとまりを作ります。異なる考え、関数、パイプラインを区切るには空行を1行だけ使い、文ごとに空行を入れることは避けてください。関数の先頭や末尾に空行を置かないでください。コメントブロックの前に空行を入れると、その説明と下のコードのつながりが明確になることがあります。
• エスケープを減らせる場合を除き、二重引用符を優先します。論理定数は TRUE と FALSE と表記します。コメントの先頭には # を付けます。コメントは判断や制約を説明するものとして残し、その目的を確認してから、単なる説明は削除してください。
• 計算を制御する引数や既定値を上書きする引数には名前を付けますが、慣例的な最初のデータ引数すべてに名前を付ける必要はありません。部分一致は避けてください。

関数とパイプ

出典：関数、パイプ。

• 名前付き関数には function(...) { ... } を使います。1つの式だけからなる短い匿名関数には \(x) ... を使えます。長い匿名関数には function() を使ってください。スタイルだけを理由に、数式ラムダやラッパーを導入しないでください。
• 長い関数定義は、一貫したインデントで複数行に記述します。return() は主に早期終了に使い、単独の行に置きます。それ以外では最後の式に任せてください。副作用を持つ関数は入力を不可視に返す場合がありますが、既存の戻り値を変更することは見た目だけの変更ではありません。
• 主なオブジェクトが1つの変換にはパイプを使います。複数のオブジェクトが関わる場合や、中間値に意味がある場合は中間値に名前を付けます。複数行のパイプでは、パイプを行末に置き、各ステップを2スペースでインデントします。短いパイプや複数の代入形式も問題ありません。
• このガイドでは |> を推奨していますが、%>% を一括変換しないでください。Rの最小バージョン、プレースホルダー、代名詞、magrittr演算子、評価の動作を確認してください。移行は、テストを行う独立した作業として扱ってください。

パッケージファイル

出典：ファイル、パッケージファイル、テスト。

• 小文字の説明的な .R ファイル名を使い、区切り文字には - または _ を一貫して使います。関数が1つだけのファイルには、その関数の名前を付けます。関連する関数をまとめたファイルには、簡潔で印象に残る名前を付けます。このガイドでは、非推奨関数のファイルに deprec- を使っています。
• ドキュメント化された公開関数は、非公開ヘルパーより前に配置します。複数の関数が同じroxygenドキュメントブロックを共有する場合は、その直後に配置します。必要に応じてセクションコメントを使います。コードを移動する前に、collate順、登録、生成ファイル、ロード時の影響を確認してください。
• テストを整理する際は、tests/testthat/test-<name>.R を R/<name>.R に対応させます。この書籍が指定しているのはテストファイルの整理方法であり、テストの設計やカバレッジの目標ではありません。
• スクリプトでは、library() の呼び出しを冒頭付近にまとめます。パッケージコード内に library() の呼び出しを追加したり、このスクリプトに関する指針からパッケージの依存関係に関する方針を推測したりしないでください。

ドキュメントと診断

出典：ドキュメント、エラーメッセージ。

• roxygen コメントはコードの隣に記述します。簡潔なセンテンスケースのタイトルを使い、末尾にピリオドは付けません。説明が長い場合は明示的に @description を使います。行頭には #' を付け、折り返したタグは一貫したインデントにし、パラメーターと戻り値について完全な文で記述します。共通の説明には @inheritParams を使います。
• R コード、引数名、値にはバッククォートを使いますが、パッケージ名がパッケージ名であるという理由だけでバッククォートを付ける必要はありません。有用な場合は @seealso、@family、リンクを追加します。roxygen でドキュメント化する内部関数には @noRd を使います。すべてのヘルパー関数に roxygen を追加しないでください。
• エラーは、問題を明確に示し、役立つ場所や詳細を添えて始めます。明確な要件には “must” を使い、操作の失敗をより自然に表す場合は “Can't” を使います。必要な場合に限り、箇条書きやヒントを使います。根拠のない診断を作り出さないでください。このガイドでは cli の規約を紹介していますが、依存関係を追加するかどうかは別途判断します。
• ドキュメントが実際のシグネチャ、デフォルト値、戻り値、例と一致していることを確認します。エラーの文言はユーザーに表示されたり、スナップショットに記録されたりする場合があります。検証ルール、条件クラス、エラーが発生するタイミングの変更は、スタイルの整理ではありません。

ggplot2（該当する場合）

出典：ggplot2。+ は行末に置き、後続のレイヤーはインデントします。データ引数の中ではなく、ggplot() を呼び出す前にデータを変換することを優先します。プロット構成を変更する場合は、既存の動作と照らし合わせて確認します。

オプションのツール

対象を限定して書式を整えるには air format R/file.R を使います（書き込みなしで確認するには air format --check R/file.R を使います）。インストールされている場合、jarl check . で lint の指摘を確認でき、ry check で型に関する問題の可能性を検出できます。プロジェクトの設定に従い、診断結果を確認せずに自動修正を適用することは避けてください。これらのツールは必須ではなく、動作が変わらないことを保証するものでもありません。利用できないツールや、既存テストの失敗があれば報告します。

例

• R/import.R をレビューする場合：次の行の内容をただ説明するだけのコメントは、スタイル上のノイズとして指摘します。tryCatch(..., error = function(e) NULL) は、レビュー中に削除するのではなく、調査が必要な バグの可能性 として扱います。
• R 4.0 をサポートするパッケージを整理する場合：依頼されたファイルの書式を整えますが、%>% とエクスポートされた名前には手を加えません。ベースパイプへの移行や公開名の変更は、互換性の分析とテストを添えて、別途提案します。

このスタイル作業をテスト設計やパッケージ基盤の作業に広げるのではなく、テスト設計には r-testthat を、パッケージ基盤には r-package-development を使ってください。