diff options
Diffstat (limited to 'Rguide.md')
-rw-r--r-- | Rguide.md | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/Rguide.md b/Rguide.md new file mode 100644 index 0000000..de27371 --- /dev/null +++ b/Rguide.md @@ -0,0 +1,109 @@ +# Google's R Style Guide + +R is a high-level programming language used primarily for statistical computing +and graphics. The goal of the R Programming Style Guide is to make our R code +easier to read, share, and verify. + +The Google R Style Guide is a fork of the +[Tidyverse Style Guide](https://style.tidyverse.org/) by Hadley Wickham +[license](https://creativecommons.org/licenses/by-sa/2.0/). Google modifications +were developed in collaboration with the internal R user community. The rest of +this document explains Google's primary differences with the Tidyverse guide, +and why these differences exist. + +## Syntax + +### Naming conventions + +Google prefers identifying functions with `BigCamelCase` to clearly distinguish +them from other objects. + +``` +# Good +DoNothing <- function() { + return(invisible(NULL)) +} +``` + +The names of private functions should begin with a dot. This helps communicate +both the origin of the function and its intended use. + +``` +# Good +.DoNothingPrivately <- function() { + return(invisible(NULL)) +} +``` + +We previously recommended naming objects with `dot.case`. We're moving away from +that, as it creates confusion with S3 methods. + +### Don't use attach() + +The possibilities for creating errors when using `attach()` are numerous. + +## Pipes + +### Right-hand assignment + +We do not support using right-hand assignment. + +``` +# Bad +iris %>% + dplyr::summarize(max_petal = max(Petal.Width)) -> results +``` + +This convention differs substantially from practices in other languages and +makes it harder to see in code where an object is defined. E.g. searching for +`foo <-` is easier than searching for `foo <-` and `-> foo` (possibly split over +lines). + +### Use explicit returns + +Do not rely on R's implicit return feature. It is better to be clear about your +intent to `return()` an object. + +``` +# Good +AddValues <- function(x, y) { + return(x + y) +} + +# Bad +AddValues <- function(x, y) { + x + y +} +``` + +### Qualifying namespaces + +Users should explicitly qualify namespaces for all external functions. + +``` +# Good +purrr::map() +``` + +We discourage using the `@import` Roxygen tag to bring in all functions into a +NAMESPACE. Google has a very big R codebase, and importing all functions creates +too much risk for name collisions. + +While there is a small performance penalty for using `::`, it makes it easier to +understand dependencies in your code. There are some exceptions to this rule. + +* Infix functions (`%name%`) always need to be imported. +* Certain `rlang` pronouns, notably `.data`, need to be imported. +* Functions from default R packages, including `datasets`, `utils`, + `grDevices`, `graphics`, `stats` and `methods`. If needed, you can `@import` + the full package. + +When importing functions, place the `@importFrom` tag in the Roxygen header +above the function where the external dependency is used. + +## Documentation + +### Package-level documentation + +All packages should have a package documentation file, in a +`packagename-package.R` file. |