r-tidyverse-style

R 包代码的 Tidyverse 风格

除非用户要求迁移，否则优先遵循包中既有的约定，而不是 tidyverse 指南。风格不能证明代码正确；清理时应保持公开行为不变。

完成任务

1. 确定范围和模式。 进行审查时，只检查指定文件或差异，不做修改。进行清理时，只更改约定好的范围。编写新代码时，先检查相邻的 R/ 文件、测试和风格配置，再选择约定。必要时检查 DESCRIPTION，了解支持的 R 版本和依赖项。
2. 保护接口。 重命名或重新组织代码之前，检查导出项、roxygen/NAMESPACE、S3/S4 方法、调用方、测试和用户可见的条件。不要把公开重命名、默认值变更、错误、返回值、依赖项或支持的 R 版本变化当作外观调整。
3. 分类观察结果。 区分风格、可维护性和潜在 bug。对于看似生成的代码，调查是否存在重复代码的注释、重复检查或辅助函数、无意义的包装器、推测性的 tryCatch() 回退，以及与行为矛盾的文档或测试。删除任何内容前，先对照调用方和测试确认；代码来源本身不能证明任何问题。这些是审查时的启发式方法，不是 tidyverse 规则。
4. 按风险顺序更改。 先格式化指定范围内的文件。然后只简化已确认的冗余，并保留说明意图或约束的注释。对涉及行为的更改（管道转换、求值顺序、控制流、公开名称、错误文本）应单独提出；只有用户授权此范围时才进行，并编写有针对性的测试。不要把风格整理变成未经请求的重构。
5. 验证并报告。 检查差异；酌情运行相关的针对性测试和更广泛的包检查。仅审查时，按优先级列出发现，并提供文件/行号引用和建议修改，不要改动文件。进行修改时，说明更改内容、暂缓事项，以及实际运行了哪些检查。不要声称风格整理等同于正确性或安全性审查。

风格规则

以下规则是对 tidyverse 风格指南（来源，参考提交 2aed77e）的有选择性转述；这不是官方的 tidyverse 技能。链接是引用，不是必读材料。只有在需要澄清规则或用户要求核实时，才打开相关章节；默认不要阅读所有章节。

语法和命名

来源：语法。

• 优先使用描述性 snake_case 名称：值使用名词，函数使用动词。点号可能会让 S3 方法名称难以辨认。重命名文件或包外部使用的名称前，请先检查兼容性。
• 使用两个空格缩进，不使用制表符。逗号后、普通中缀运算符两侧，以及命名参数中 = 两侧都要加空格；但括号内侧、$、::、:、^ 或一元 - 两侧不加空格。整洁求值运算符有例外。优先使用语法感知的格式化工具，而不是正则表达式编辑。
• 赋值使用 <-，命名参数使用 =；避免使用分号，也不要在一行写多个语句。
• 左花括号放在行尾，右花括号放在行首，else 放在前一个 } 旁边。多行分支和循环使用花括号。不要将 if 替换为向量化的 ifelse()，也不要在未检查语义的情况下将 &/| 改为 &&/||。
• 长调用的参数分行书写，并保持缩进一致。尽量让行长易于阅读（80 个字符是目标，不是硬性限制）。
• 将相关语句分组成便于辨认的段落；用一个空行分隔不同的思路、函数或管道，而不是在每条语句之间都加空行。函数开头或结尾不要留空行。注释块前的空行有助于将说明与下方代码联系起来。
• 优先使用双引号，除非单引号能减少转义；逻辑常量写作 TRUE 和 FALSE。注释以 # 开头。保留用于说明决策或限制的注释；删除叙述性注释前，先确认其用途。
• 对控制计算或覆盖默认值的参数使用参数名，但不要求给每个常规的首个数据参数都加名称。避免部分匹配。

函数和管道

来源：函数、管道。

• 命名函数使用 function(...) { ... }。简短的单表达式匿名函数可以使用 \(x) ...；较长的匿名函数使用 function()。不要仅仅为了风格而引入公式 lambda 或包装器。
• 较长的函数定义应分行书写，并保持缩进一致。return() 主要用于提前退出，且单独占一行；否则依赖最后一个表达式。产生副作用的函数可以隐式返回输入，但更改现有返回值并非纯粹的格式调整。
• 对单个主要对象进行转换时使用管道；涉及多个对象或中间结果有意义时，为中间结果命名。多行管道中，将管道符放在行尾，各步骤缩进两个空格。短管道和多种赋值布局都可以接受。
• 指南推荐使用 |>，但不要批量将 %>% 替换为它：请检查最低 R 版本、占位符、代词、magrittr 运算符和求值行为。将迁移作为单独的工作进行测试。

包文件

来源：文件、包文件、测试。

• 使用描述性的小写 .R 文件名，并统一使用 - 或 _ 作为分隔符。单函数文件以函数命名；包含相关函数的文件使用简洁且能体现特点的名称。指南使用 deprec- 作为已弃用函数文件的前缀。
• 将有文档记录的公共函数放在私有辅助函数之前。如果多个函数共用一个 roxygen 文档块，应紧接在该文档块之后放置。适当时使用分节注释。移动代码前，请检查 collate 顺序、注册、生成文件和加载时的副作用。
• 整理测试时，让 tests/testthat/test-<name>.R 与 R/<name>.R 对应。本书规定的是测试文件的组织方式，而非测试设计或覆盖率目标。
• 在脚本中，将 library() 调用集中放在靠近顶部的位置。不要在包代码中添加 library() 调用，也不要根据这份脚本指南推断包的依赖策略。

文档与诊断

来源：Documentation、Error messages。

• 将 roxygen 注释放在代码旁边。使用简洁的句首字母大写标题，末尾不加句号；较长的描述使用显式的 @description。行首加上 #' ，统一缩进换行的标签，写完整的参数和返回值说明句，并使用 @inheritParams 复用共享文本。
• R 代码、参数名和值使用反引号；不要仅仅因为包名是包名就给它们加反引号。在适用时添加 @seealso、@family 和链接。用 roxygen 为内部函数编写文档时使用 @noRd；不要给每个辅助函数都添加 roxygen。
• 错误信息先清楚说明问题，并提供有用的位置或详细信息。明确要求时使用 “must”，操作失败时用 “Can't” 更自然则使用 “Can't”。只有在确有必要时才使用项目符号或提示；不要臆造诊断信息。本指南介绍了 cli 的惯例，但是否添加依赖是另一项独立决策。
• 核对文档是否与实际签名、默认值、返回值和示例一致。错误措辞可能会直接显示给用户或被快照测试捕获；更改验证规则、条件类或错误触发时机不属于风格清理。

ggplot2（适用时）

来源：ggplot2。将 + 放在行尾，后续图层缩进；与其在 ggplot() 的 data 参数中转换数据，不如在调用 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 的包：格式化请求的文件，但保留 %>% 和导出名称不变。任何 base pipe 迁移或公开名称重命名都应单独提出，并分析兼容性、进行测试。

测试设计使用 r-testthat，包基础设施使用 r-package-development，不要将这次风格检查扩展为上述任一任务。