/
Developer_Style_Guide.Rmd
149 lines (114 loc) · 4.25 KB
/
Developer_Style_Guide.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
title: "Developer Style Guide"
author: "Mazama Science"
date: "2024-03-08"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Developer Style Guide}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
# R Style Guide
This document describes the coding style used within the package. Having a
consistent style enhances the readability and "understandability" of the code
and makes it easier for users and developers to work with this package and
with other, related packages from [Mazama Science](http://mazamascience.com).
## Naming Objects
Naming variables is one of the most important things to get right to make your
code readable and understandable to future readers of the code _(perhaps even
yourself!)_. Having a system for creating names also makes it easier to come up
with new ones.
Mazama Science embraces **`lowerCamelCase`** for object names.
With the casing settled, we use an ornithologist’s sensibility for how to
identify things:
* What is it? — a `bird`
* What kind of bird is it? — a `blackBird`
* What kind of blackBird is it? — a `redwingedBlackBird`
It’s a simple system: start with a noun and prefix it with descriptors until
it is uniquely identified.
In this system we would never have a variable called: `num_hours`. Instead we go
through our process:
* What is it? — _(Hmm. What noun describes this? Ah yes!)_ — a `count`
* What kind of count is it? — _(It's not a "head count" or a "body count".)_
It's an `hourCount`.
For complex objects it is often helpful to give readers of the code a hint as to
what type of object it is so they will know how to work with it. We often use
variable names like:
* `sts` — a single time series object
* `mts` — a multiple time series object
* `tidyDF` — a 'tidy' dataframe representing a `sts` object
We occasionally use ‘_’ to create classes of similar variables that are
otherwise hard to name, e.g.:
```
sts_01
sts_02
sts_tidy
```
## Naming Functions
Most functions should strive to be atomic in nature and should do one thing
really well. Think of them as individual _Lego_ bricks that we click together
to achieve more advanced functionality. Where objects are _**well described nouns**_,
functions are _**well described verbs**_ that describe what they do as in:
```
sts_filter()
sts_filterDate()
sts_join()
sts_toTidyDF()
sts_trimDate()
...
```
All of these functions begin with `sts_` because they are for creating or working
with `sts` objects. Many of these functions accept a `sts` object as their first
argument and return a modified `sts`. This means that they can be used with the
`%>%` "pipe" operator and chained together as in:
```
example_tidy <-
example_sts %>%
sts_filter(
temperature > 50,
humidity < 20,
pm25_A > 100
) %>%
sts_toTidyDF()
```
## Naming Files
Each file should contain a single function of the same name. Thus, the function
named `sts_filterDate()` is defined in `sts_filterDate.R`. An exception is made
for small, mostly internal functions used in conjunction with a particular type
of object or activity. These can be stored together in a file named `utils-~`:
```
utils-sts.R
utils-mts.R
utils-pipe.R
```
## Syntax
We generally adhere to the [Wickham Style Guide](http://adv-r.had.co.nz/Style.html)
for syntax with a few exceptions:
### Spacing
**Do** place spaces around code in parentheses if it is an `if` test:
```
if ( <logical expression part1> && <logical expression part2> ) {
...
}
```
When debugging, this makes it much easier to select the logical test with a
cursor and paste it into the RStudio console.
### Lists
We generally like to specify R lists with each `parameter = value` pair on a
separate line. This goes for regular lists and for named argument lists passed
to a function:
```
example_filterDate <-
example_sts %>%
sts_filterDate(
startdate = 20180808,
enddate = 20180815
)
```
Coding this way makes it easy to see which function arguments are being passed.
It also eases future refactoring of the code when additional arguments need to
be added or the order of arguments need to be changed.
-----
It is our belief that good code should be both readable and understandable and
should inspire others to copy and innovate on their own.
**_Mazama Science_**