1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2
"http://www.w3.org/TR/REC-html4/strict.dtd">
5
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
6
<link rel="stylesheet" type="text/css"
7
href="http://www.corp.google.com/eng/docstyle.css">
8
<title>Google's R Style Guide</title>
9
<style type="text/css">
10
ul.NoBullet {list-style-type: none}
16
<!---------------------------------------------------------------------------->
18
<h1>Google's R Style Guide</h1>
21
R is a high-level programming language used primarily for statistical
22
computing and graphics. The goal of the R Programming Style Guide
23
is to make our R code easier to read, share, and verify. The rules
24
below were designed in collaboration with the entire R user community
28
<!---------------------------------------------------------------------------->
31
<h2><li>Summary: R Style Rules</li></h2>
33
<li><a href=#filenames>File Names</a>: end in <code>.R</code></li>
34
<li><a href=#identifiers>Identifiers</a>: <code>variable.name</code>,
35
<code>FunctionName</code>, <code>kConstantName</code></li>
37
<li><a href=#linelength>Line Length</a>: maximum 80 characters</li>
38
<li><a href=#indentation>Indentation</a>: two spaces, no tabs</li>
39
<li><a href=#spacing>Spacing</a></li>
40
<li><a href=#curlybraces>Curly Braces</a>: first on same line, last on
42
<li><a href=#assignment>Assignment</a>: use <code><-</code>, not
45
<li><a href=#semicolons>Semicolons</a>: don't use them</li>
46
<li><a href=#generallayout> General Layout and Ordering</a></li>
47
<li><a href=#comments> Commenting Guidelines</a>: all comments begin
48
with <code>#</code> followed by a space; inline comments need two
49
spaces before the <code>#</code></li>
51
<li><a href=#functiondefinition>Function Definitions and Calls</a></li>
52
<li><a href=#functiondocumentation> Function Documentation</a></li>
53
<li><a href=#examplefunction> Example Function</a></li>
54
<li><a href=#todo> TODO Style</a>: <code>TODO(username)</code></li>
57
<h2><li>Summary: R Language Rules</li></h2>
59
<li><a href=#attach> <code>attach</code></a>: avoid using it</li>
60
<li><a href=#functionlanguage> Functions</a>:
61
errors should be raised using <code>stop()</code></li>
63
<li><a href=#object> Objects and Methods</a>: avoid S4 objects and
64
methods when possible; never mix S3 and S4 </li>
70
<!---------------------------------------------------------------------------->
72
<h3><li>Notation and Naming</li></h3>
75
<h4 id="filenames"><li>File Names</li></h4>
77
File names should end in <code>.R</code> and, of course, be
79
<br> GOOD: <code>predict_ad_revenue.R</code>
80
<br> BAD: <code><span style="color:red">foo.R</span></code>
83
<h4 id="identifiers"><li>Identifiers</li></h4>
85
Don't use underscores ( <code>_</code> ) or hyphens
86
( <code>-</code> ) in identifiers.
87
Identifiers should be named according to the following conventions.
88
Variable names should have all lower case letters and words
89
separated with dots (<code>.</code>);
90
function names have initial capital letters and no dots
92
constants are named like functions but with an initial
97
<li><code>variable.name </code>
98
<br> GOOD: <code>avg.clicks</code>
99
<br> BAD: <code><span style="color:red">avg_Clicks
100
</span></code>, <code><span style="color:red">avgClicks
104
<li><code>FunctionName </code>
105
<br> GOOD: <code>CalculateAvgClicks</code>
106
<br> BAD: <code><span style="color:red">calculate_avg_clicks
108
<code><span style="color:red">calculateAvgClicks</span></code>
110
<br> Make function names verbs.
111
<br><em>Exception: When creating a classed object, the function
112
name (constructor) and class should match (e.g., lm).</em>
113
<li><code>kConstantName </code></li>
117
<!---------------------------------------------------------------------------->
119
<h3><li>Syntax</li></h3>
121
<ul class="NoBullet">
122
<h4 id="linelength"><li>Line Length</li></h4>
124
The maximum line length is 80 characters.
126
<h4 id="indentation"><li>Indentation</li></h4>
128
When indenting your code, use two spaces. Never use tabs or mix
130
<br><em>Exception: When a line break occurs inside parentheses,
131
align the wrapped line with the first character inside the
135
<h4 id="spacing"><li>Spacing</li></h4>
137
Place spaces around all binary operators (<code>=</code>,
138
<code>+</code>, <code>-</code>, <code><-</code>, etc.).
139
<br><em> Exception: Spaces around <code>=</code>'s are
140
optional when passing parameters in a function call.</em>
144
Do not place a space before a comma, but always place one after a
146
<br><br> GOOD:<pre><code>tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"])
147
total <- sum(x[, 1])
148
total <- sum(x[1, ])</code></pre>
152
BAD:<pre><code><span style="color:red">tabPrior <- table(df[df$daysFromOpt<0, "campaignid"]) # Needs spaces around '<'
153
tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"]) # Needs a space after the comma
154
tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"]) # Needs a space before <-
155
tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"]) # Needs spaces around <-
156
total <- sum(x[,1]) # Needs a space after the comma
157
total <- sum(x[ ,1]) # Needs a space after the comma, not before</span></code></pre>
161
Place a space before left parenthesis, except in a function call.
165
<br><code>if (debug)</code>
170
<br><code><span style="color:red">if(debug)</span></code>
173
Extra spacing (i.e., more than one space in a row) is okay if it
174
improves alignment of equals signs or arrows (<code><-</code>).
176
<pre><code>plot(x = xCoord,
177
y = dataMat[, makeColName(metric, ptiles[1], "roiOpt")],
179
xlab = "dates",
181
main = (paste(metric, " for 3 samples ", sep="")))
185
Do not place spaces around code in parentheses or square brackets.
186
<br><em> Exception: Always place a space after a comma.</em>
189
GOOD: <pre><code>if (debug)
194
BAD:<pre><code><span style="color:red">if ( debug ) # No spaces around debug
195
x[1,] # Needs a space after the comma </span></code></pre>
197
<h4 id="curlybraces"><li>Curly Braces</li></h4>
199
An opening curly brace should never go on its own line; a closing
200
curly brace should always go on its own line. You may omit curly
201
braces when a block consists of a single statement; however, you
202
must <em>consistently</em> either use or not use curly braces for
203
single statement blocks.
208
ylim <- c(0, 0.06)
215
ylim <- c(0, 0.06)</pre></code>
218
Always begin the body of a block on a new line.
222
<br><code><span style="color:red"> if (is.null(ylim))
223
ylim <- c(0, 0.06)</span></code>
224
<br><code><span style="color:red"> if (is.null(ylim))
225
{ylim <- c(0, 0.06)} </span></code>
228
<h4 id="assignment"><li>Assignment</li></h4>
230
Use <code><-</code>, not <code>=</code>, for assignment.
234
<br><code> x <- 5 </code>
239
<br><code><span style="color:red"> x = 5</span></code>
241
<h4 id="semicolons"><li>Semicolons</li></h4>
243
Do not terminate your lines with semicolons or use semicolons to
244
put more than one command on the same line. (Semicolons are not
245
necessary, and are omitted for consistency with other Google style
251
<!---------------------------------------------------------------------------->
253
<h3><li> Organization </li></h3>
254
<ul class="NoBullet">
255
<h4 id="generallayout"><li>General Layout and Ordering</li></h4>
257
If everyone uses the same general ordering, we'll be able to
258
read and understand each other's scripts faster and more easily.
262
<li>Copyright statement comment
264
<li>File description comment, including purpose of
265
program, inputs, and outputs
266
<li><code>source()</code> and <code>library()</code> statements
267
<li>Function definitions
268
<li>Executed statements, if applicable (e.g.,
269
<code> print</code>, <code>plot</code>)
273
Unit tests should go in a separate file named
274
<code>originalfilename_unittest.R</code>.
276
<h4 id="comments"><li>Commenting Guidelines</li></h4>
278
Comment your code. Entire commented lines should begin with
279
<code>#</code> and one space.
283
Short comments can be placed after code preceded by two spaces,
284
<code>#</code>, and then one space.
286
<pre><code># Create histogram of frequency of campaigns by pct budget spent.
288
breaks = "scott", # method for choosing number of buckets
289
main = "Histogram: fraction budget spent by campaignid",
290
xlab = "Fraction of budget spent",
291
ylab = "Frequency (count of campaignids)")
294
<h4 id="functiondefinition"><li> Function Definitions and
297
Function definitions should first list arguments without default
298
values, followed by those with default values.
301
In both function definitions and function calls, multiple
302
arguments per line are allowed; line breaks are only allowed
305
<pre><code>PredictCTR <- function(query, property, numDays,
310
<pre><code><span style="color:red">PredictCTR <- function(query, property, numDays, showPlot =
313
<p> Ideally, unit tests should serve as sample function calls (for
314
shared library routines).
315
<h4 id="functiondocumentation"><li> Function Documentation </li></h4>
316
<p> Functions should contain a comments section immediately below
317
the function definition line. These comments should consist of a
318
one-sentence description of the function; a list of the function's
319
arguments, denoted by <code>Args:</code>, with a description of
320
each (including the data type); and a description of the return
321
value, denoted by <code>Returns:</code>. The comments should be
322
descriptive enough that a caller can use the function without
323
reading any of the function's code.
326
<h4 id="examplefunction"><li> Example Function </li></h4><pre><code>
328
CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
329
# Computes the sample covariance between two vectors.
332
# x: One of two vectors whose sample covariance is to be calculated.
333
# y: The other vector. x and y must have the same length, greater than one,
334
# with no missing values.
335
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
338
# The sample covariance between x and y.
341
if (n <= 1 || n != length(y)) {
342
stop("Arguments x and y have invalid lengths: ",
343
length(x), " and ", length(y), ".")
345
if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
346
stop(" Arguments x and y must not have missing values.")
348
covariance <- var(x, y)
350
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
356
<h4 id="todo"><li> TODO Style </li></h4>
357
<p> Use a consistent style for TODOs throughout your code.
358
<br><CODE>TODO(username): Explicit description of action to
362
<!---------------------------------------------------------------------------->
364
<h3><li> Language </li></h3>
366
<ul class="NoBullet">
367
<h4 id="attach"><li> Attach </li></h4>
368
<p> The possibilities for creating errors when using
369
<code>attach</code> are numerous. Avoid it.
370
<h4 id="functionlanguage"><li>Functions </li></h4>
371
<p> Errors should be raised using <code>stop()</code>.
372
<h4 id="object"><li>Objects and Methods</li></h4>
374
<p> The S language has two object systems, S3 and S4, both of which
375
are available in R. S3 methods are more interactive and flexible,
376
whereas S4 methods are more formal and rigorous. (For an illustration
377
of the two systems, see Thomas Lumley's
378
"Programmer's Niche: A Simple
379
Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
380
<a href="http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
381
http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf</a>.)
382
<p>Use S3 objects and methods unless there is a strong reason to use
383
S4 objects or methods. A primary justification for an S4 object
384
would be to use objects directly in C++ code. A primary
385
justification for an S4 generic/method would be to dispatch on two
387
<p>Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and
392
<!---------------------------------------------------------------------------->
393
<h3><li> Exceptions </li></h3>
395
The coding conventions described above should be followed, unless
396
there is good reason to do otherwise. Exceptions include
397
legacy code and modifying third-party code.
399
<!---------------------------------------------------------------------------->
400
<h3><li> Parting Words </li></h3>
402
Use common sense and BE CONSISTENT.
404
If you are editing code, take a few minutes to look at the code around
405
you and determine its style. If others use spaces around their
407
clauses, you should, too. If their comments have little boxes of stars
408
around them, make your comments have little boxes of stars around them,
412
The point of having style guidelines is to have a common vocabulary of
413
coding so people can concentrate on <em>what</em> you are saying,
414
rather than on <em>how</em> you are saying it. We present global style
416
know the vocabulary. But local style is also important. If code you add
417
to a file looks drastically different from the existing code around it,
418
the discontinuity will throw readers out of their rhythm when they go to
419
read it. Try to avoid this.
421
OK, enough writing about writing code; the code itself is much more
422
interesting. Have fun!
424
<!---------------------------------------------------------------------------->
425
<h3><li> References </li></h3>
427
<a href="http://www.maths.lth.se/help/R/RCC/">
428
http://www.maths.lth.se/help/R/RCC/</a> - R Coding Conventions
430
<a href="http://ess.r-project.org/">http://ess.r-project.org/</a> - For
431
emacs users. This runs R in your emacs and has an emacs mode.
435
<!---------------------------------------------------------------------------->
added
removed
third_party/google-styleguide/google-r-style.html
