styleguide

Google 的 R 语言风格指南

R 是一种高级编程语言，主要用于统计计算和图形。R 编程风格指南的目标是使我们的 R 代码更易于阅读、分享和验证。

Google R 语言风格指南是 Hadley Wickham 的 Tidyverse 风格指南 的一个分支，基于 许可协议。 Google 的修改是在内部 R 用户社区的合作下开发的。 本文档的其余部分解释了 Google 与 Tidyverse 指南的主要差异，以及这些差异存在的原因。

语法

命名规范

Google 倾向于使用 BigCamelCase 标识函数，以便清楚地将它们与其他对象区分开来。

# Good
DoNothing <- function() {
  return(invisible(NULL))
}

私有函数的名称应以点开头。 这有助于传达函数的来源及其预期用途。

# Good
.DoNothingPrivately <- function() {
  return(invisible(NULL))
}

我们之前建议使用 dot.case 命名对象。 我们正在逐渐放弃它，因为它会与 S3 方法产生混淆。

不要使用 attach()

使用 attach() 时，产生错误的可能性很多。

管道

右侧赋值

我们不支持使用右侧赋值。

# Bad
iris %>%
  dplyr::summarize(max_petal = max(Petal.Width)) -> results

此约定与其他语言中的实践大相径庭，并且使在代码中查看对象定义的位置变得更加困难。 例如，搜索 foo <- 比搜索 foo <- 和 -> foo （可能跨行）更容易。

使用显式返回

不要依赖 R 的隐式返回功能。 最好明确你想要 return() 一个对象。

# Good
AddValues <- function(x, y) {
  return(x + y)
}

# Bad
AddValues <- function(x, y) {
  x + y
}

限定命名空间

用户应显式限定所有外部函数的命名空间。

# Good
purrr::map()

我们不鼓励使用 @import Roxygen 标签将所有函数引入到 NAMESPACE 中。 Google 有一个非常大的 R 代码库，导入所有函数会带来太多的名称冲突风险。

虽然使用 :: 会带来很小的性能损失，但它可以更容易地理解代码中的依赖关系。 此规则也有一些例外。

• 中缀函数 (%name%) 始终需要导入。
• 某些 rlang 代词，尤其是 .data，需要导入。
• 来自默认 R 包的函数，包括 datasets、utils、grDevices、graphics、stats 和 methods。 如果需要，您可以 @import 整个包。

导入函数时，请将 @importFrom 标签放在使用外部依赖项的函数上方的 Roxygen 标头中。

文档

包级别的文档

所有包都应该有一个包文档文件，位于 packagename-package.R 文件中。

此站点是开源的。 改进此页面。