用途
本技能是一份 R 语言代码风格指南与函数编写最佳实践，用于在编写 R 代码时保持一致的命名、空格、结构、排版与函数设计。
主要能力
命名规范
- 所有名称使用 snake_case。
- 变量名用名词，函数名用动词。
- 除 S3 方法外避免使用点号。
- 示例：
day_one、calculate_mean、user_data；避免DayOne、calculate.mean、userData。
空格与排版
- 运算符两侧加空格：
x <- 1 + 2。 - 索引与参数示例：
x[, 1]、mean(x, na.rm = TRUE)。 - 管道格式化：
data |> filter(...) |> group_by(...) |> summarise(...)，每步换行。 - 赋值使用
<-，=仅用于函数参数。
缩进与行长
- 使用 2 个空格缩进，不使用制表符。
- 行长尽量不超过 80 字符。
- 长函数调用每个参数单独一行；长管道链每步单独一行。
注释
- 注释解释“为什么”而非“是什么”。
- 避免仅重复代码的注释。
文件组织
按以下顺序组织文件：
- 顶部加载包（如
library(dplyr)）。 - source 辅助文件（如
source("R/helpers.R")）。 - 定义常量（如
MAX_ITERATIONS <- 1000）。 - 定义函数。
- 主脚本逻辑（非包项目）。
函数设计
- 单一职责：每个函数只做一件事，例如
read_and_validate()与validate_columns()分离。 - 返回值：复杂函数使用显式
return()，简单函数可用隐式返回；避免无理由的中途返回，允许提前退出。 - 类型稳定输出：使用
map_dbl()、map_chr()、map_lgl()等保证返回类型一致。 - 默认参数：设置合理默认值，可选参数可用
NULL默认。 - 错误处理：优先使用
cli::cli_abort()替代stop()，消息结构为问题陈述加上下文要点。
cli 内联标记
{.arg x}：参数名。{.fn foo}：函数名。{.cls {class(x)}}：类名。{.val {value}}：字面值。{?s}：复数化。
tidyverse API 约定
- 数据优先参数：数据作为第一个参数以便管道使用。
- 非标准参数加
.前缀以避免冲突，如.data、.by。 - 一致返回类型：例如始终返回 tibble。
常见风格错误
- 避免不一致空格、多余括号、使用
T/F代替TRUE/FALSE、用分号分隔语句、使用attach()。
使用方式
在编写 R 代码时参照本指南的规则与示例，统一命名、排版、注释、文件结构与函数设计。资料未提供具体的安装命令或调用方式。
适用场景
适用于编写 R 代码、进行代码审查或建立团队 R 代码规范时参考。
限制
资料未提供该技能的安装方式、运行环境要求、收费信息或平台支持情况。