mirror of
https://github.com/tiennm99/styleguide.git
synced 2026-10-16 02:15:53 +00:00
Replace external R style guide
Internally, we've moved to the Tidyverse Style Guide: style.tidyverse.org The new file for Rguide.md reflects this fact and notes where we differ.
This commit is contained in:
1 parent
9c6b371f41
commit
cee8f1a722
3 files changed
+110
-448
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user