Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / google-styleguide / 1b206ee36263b16ec18f7b2f86a2b770b7490844 / . / Rguide.xml
blob: ef8787263085cfcf93bb613444c2b58616651bf5 [file] [log] [blame]
Ted Osborne505ba682018-01-30 12:36:50 -0500[diff] [blame]1<?xml version="1.0"?>
2<html xmlns="http://www.w3.org/1999/xhtml">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
5 <link rel="stylesheet" type="text/css" href="styleguide.css"/>
6 <title>Google's R Style Guide</title>
7 </head>
8
9 <body>
10
11 <h1>Google's R Style Guide</h1>
12
13 <p>
14 R is a high-level programming language used primarily for
15 statistical computing and graphics. The goal of the R
16 Programming Style Guide is to make our R code easier to read,
17 share, and verify. The rules below were designed in
18 collaboration with the entire R user community at Google.
19
20 </p>
21
22
23
24
25
26
27 <h2>Summary: R Style Rules</h2>
28
29 <ol>
30 <li><a href="#filenames">File Names</a>: end in <code>.R</code></li>
31 <li><a href="#identifiers">Identifiers</a>: <code>variable.name</code>
32 (or <code>variableName</code>),
33 <code>FunctionName</code>, <code>kConstantName</code></li>
34 <li><a href="#linelength">Line Length</a>: maximum 80 characters</li>
35 <li><a href="#indentation">Indentation</a>: two spaces, no tabs</li>
36 <li><a href="#spacing">Spacing</a></li>
37 <li><a href="#curlybraces">Curly Braces</a>: first on same line, last on
38 own line</li>
39 <li><a href="#else">else</a>: Surround else with braces </li>
40 <li><a href="#assignment">Assignment</a>: use <code>&lt;-</code>, not
41 <code>=</code></li>
42 <li><a href="#semicolons">Semicolons</a>: don't use them</li>
43 <li><a href="#generallayout"> General Layout and Ordering</a></li>
44 <li><a href="#comments"> Commenting Guidelines</a>: all comments begin
45 with <code>#</code> followed by a space; inline comments need two
46 spaces before the <code>#</code></li>
47 <li><a href="#functiondefinition">Function Definitions and Calls</a></li>
48 <li><a href="#functiondocumentation"> Function Documentation</a></li>
49 <li><a href="#examplefunction"> Example Function</a></li>
50 <li><a href="#todo"> TODO Style</a>: <code>TODO(username)</code></li>
51 </ol>
52
53 <h2>Summary: R Language Rules</h2>
54 <ol>
55 <li><a href="#attach"> <code>attach</code></a>: avoid using it</li>
56 <li><a href="#functionlanguage"> Functions</a>:
57 errors should be raised using <code>stop()</code></li>
58 <li><a href="#object"> Objects and Methods</a>: avoid S4 objects and
59 methods when possible; never mix S3 and S4 </li>
60 </ol>
61
62 <h3>Notation and Naming</h3>
63
64 <h4 id="filenames">File Names</h4>
65 <p>
66 File names should end in <code>.R</code> and, of course, be
67 meaningful.
68 <br/> GOOD: <code>predict_ad_revenue.R</code>
69 <br/> BAD: <code><span style="color:red">foo.R</span></code>
70 </p>
71
72 <h4 id="identifiers">Identifiers</h4>
73 <p>
74 Don't use underscores ( <code>_</code> ) or hyphens
75 ( <code>-</code> ) in identifiers.
76 Identifiers should be named according to the following conventions.
77 The preferred form for variable names is all lower case
78 letters and words separated with dots
79 (<code>variable.name</code>), but <code>variableName</code>
80 is also accepted;
81 function names have initial capital letters and no dots
82 (<code>FunctionName</code>);
83 constants are named like functions but with an initial
84 <code>k</code>.
85 </p>
86 <ul>
87 <li><code>variable.name</code> is preferred, <code>variableName</code> is accepted
88 <br/> GOOD: <code>avg.clicks</code>
89 <br/> OK: <code>avgClicks</code>
90 <br/> BAD: <code><span style="color:red">avg_Clicks</span></code>
91 </li>
92 <li><code>FunctionName </code>
93 <br/> GOOD: <code>CalculateAvgClicks</code>
94 <br/> BAD: <code><span style="color:red">calculate_avg_clicks
95 </span></code>,
96 <code><span style="color:red">calculateAvgClicks</span></code>
97 <br/> Make function names verbs.
98 <br/><em>Exception: When creating a classed object, the function
99 name (constructor) and class should match (e.g., lm).</em></li>
100 <li><code>kConstantName </code></li>
101 </ul>
102
103
104 <h3>Syntax</h3>
105
106 <h4 id="linelength">Line Length</h4>
107<p>
108 The maximum line length is 80 characters.
109</p>
110
111 <h4 id="indentation">Indentation</h4>
112 <p>
113 When indenting your code, use two spaces. Never use tabs or mix
114 tabs and spaces.
115 <br/><em>Exception: When a line break occurs inside parentheses,
116 align the wrapped line with the first character inside the
117 parenthesis.</em>
118 </p>
119
120 <h4 id="spacing">Spacing</h4>
121 <p>
122 Place spaces around all binary operators (<code>=</code>,
123 <code>+</code>, <code>-</code>, <code>&lt;-</code>, etc.).
124 <br/><em> Exception: Spaces around <code>=</code>'s are
125 optional when passing parameters in a function call.</em>
126 </p>
127 <p>
128 Do not place a space before a comma, but always place one after a
129 comma.
130 <br/><br/> GOOD:
131 </p>
132<pre>tab.prior &lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"])
133total &lt;- sum(x[, 1])
134total &lt;- sum(x[1, ])</pre>
135 <p>
136 BAD:
137 </p>
138<pre><span style="color:red">tab.prior &lt;- table(df[df$days.from.opt&lt;0, "campaign.id"]) # Needs spaces around '&lt;'
139tab.prior &lt;- table(df[df$days.from.opt &lt; 0,"campaign.id"]) # Needs a space after the comma
140tab.prior&lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs a space before &lt;-
141tab.prior&lt;-table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs spaces around &lt;-
142total &lt;- sum(x[,1]) # Needs a space after the comma
143total &lt;- sum(x[ ,1]) # Needs a space after the comma, not before</span>
144</pre>
145 <p>
146 Place a space before left parenthesis, except in a function call.
147 </p>
148 <p>
149 GOOD:
150 <br/><code>if (debug)</code>
151 </p>
152 <p>
153 BAD:
154 <br/><code><span style="color:red">if(debug)</span></code>
155 </p>
156 <p>
157 Extra spacing (i.e., more than one space in a row) is okay if it
158 improves alignment of equals signs or arrows (<code>&lt;-</code>).
159 </p>
160<pre>plot(x = x.coord,
161 y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
162 ylim = ylim,
163 xlab = "dates",
164 ylab = metric,
165 main = (paste(metric, " for 3 samples ", sep = "")))
166</pre>
167 <p>
168 Do not place spaces around code in parentheses or square brackets.
169 <br/><em> Exception: Always place a space after a comma.</em>
170 </p>
171 <p>
172 GOOD:</p><pre>if (debug)
173x[1, ]</pre>
174 <p>
175 BAD:</p><pre><span style="color:red">if ( debug ) # No spaces around debug
176x[1,] # Needs a space after the comma </span></pre>
177
178 <h4 id="curlybraces">Curly Braces</h4>
179 <p>
180 An opening curly brace should never go on its own line; a closing
181 curly brace should always go on its own line. You may omit curly
182 braces when a block consists of a single statement; however, you
183 must <em>consistently</em> either use or not use curly braces for
184 single statement blocks.
185 </p>
186 <pre>
187if (is.null(ylim)) {
188 ylim &lt;- c(0, 0.06)
189}</pre>
190 <p>
191 xor (but not both)
192 </p>
193 <pre>
194if (is.null(ylim))
195 ylim &lt;- c(0, 0.06)</pre>
196 <p>
197 Always begin the body of a block on a new line.
198 </p>
199 <p>
200 BAD:
201 <br/><code><span style="color:red"> if (is.null(ylim))
202 ylim &lt;- c(0, 0.06)</span></code>
203 <br/><code><span style="color:red"> if (is.null(ylim))
204 {ylim &lt;- c(0, 0.06)} </span></code>
205 </p>
206
207 <h4 id="else">Surround else with braces</h4>
208 <p>
209 An <code>else</code> statement should always be surrounded on the
210 same line by curly braces.</p>
211 <pre>
212if (condition) {
213 one or more lines
214} else {
215 one or more lines
216}
217</pre>
218 <p>
219 BAD:<br/>
220 </p>
221 <pre style="color:red">
222if (condition) {
223 one or more lines
224}
225else {
226 one or more lines
227}
228</pre>
229 <p>
230 BAD:<br/>
231 </p>
232 <pre style="color:red">
233if (condition)
234 one line
235else
236 one line
237</pre>
238
239 <h4 id="assignment">Assignment</h4>
240 <p>
241 Use <code>&lt;-</code>, not <code>=</code>, for assignment.
242 </p>
243 <p>
244 GOOD:
245 <br/><code> x &lt;- 5 </code>
246 </p>
247 <p>
248 BAD:
249 <br/><code><span style="color:red"> x = 5</span></code>
250 </p>
251 <h4 id="semicolons">Semicolons</h4>
252 <p>
253 Do not terminate your lines with semicolons or use semicolons to
254 put more than one command on the same line. (Semicolons are not
255 necessary, and are omitted for consistency with other Google style
256 guides.)
257 </p>
258
259
260 <h3> Organization </h3>
261 <h4 id="generallayout">General Layout and Ordering</h4>
262 <p>
263 If everyone uses the same general ordering, we'll be able to
264 read and understand each other's scripts faster and more easily.
265 </p>
266 <ol>
267 <li>Copyright statement comment </li>
268 <li>Author comment</li>
269 <li>File description comment, including purpose of
270 program, inputs, and outputs</li>
271 <li><code>source()</code> and <code>library()</code> statements</li>
272 <li>Function definitions</li>
273 <li>Executed statements, if applicable (e.g.,
274 <code> print</code>, <code>plot</code>)</li>
275 </ol>
276 <p>
277 Unit tests should go in a separate file named
278 <code>originalfilename_test.R</code>.
279 </p>
280 <h4 id="comments">Commenting Guidelines</h4>
281 <p>
282 Comment your code. Entire commented lines should begin with
283 <code>#</code> and one space.
284 </p>
285 <p>
286 Short comments can be placed after code preceded by two spaces,
287 <code>#</code>, and then one space.
288 </p>
289<pre># Create histogram of frequency of campaigns by pct budget spent.
290hist(df$pct.spent,
291 breaks = "scott", # method for choosing number of buckets
292 main = "Histogram: fraction budget spent by campaignid",
293 xlab = "Fraction of budget spent",
294 ylab = "Frequency (count of campaignids)")
295</pre>
296 <h4 id="functiondefinition">Function Definitions and
297 Calls</h4>
298 <p>
299 Function definitions should first list arguments without default
300 values, followed by those with default values.
301 </p>
302 <p>
303 In both function definitions and function calls, multiple
304 arguments per line are allowed; line breaks are only allowed
305 between assignments.
306 <br/>GOOD:
307 </p>
308<pre>PredictCTR &lt;- function(query, property, num.days,
309 show.plot = TRUE)
310</pre>
311 BAD:
312<pre><span style="color:red">PredictCTR &lt;- function(query, property, num.days, show.plot =
313 TRUE)
314</span></pre>
315 <p> Ideally, unit tests should serve as sample function calls (for
316 shared library routines).
317 </p>
318 <h4 id="functiondocumentation">Function Documentation</h4>
319 <p> Functions should contain a comments section immediately below
320 the function definition line. These comments should consist of a
321 one-sentence description of the function; a list of the function's
322 arguments, denoted by <code>Args:</code>, with a description of
323 each (including the data type); and a description of the return
324 value, denoted by <code>Returns:</code>. The comments should be
325 descriptive enough that a caller can use the function without
326 reading any of the function's code.
327 </p>
328
329 <h4 id="examplefunction">Example Function</h4>
330<pre>
331CalculateSampleCovariance &lt;- function(x, y, verbose = TRUE) {
332 # Computes the sample covariance between two vectors.
333 #
334 # Args:
335 # x: One of two vectors whose sample covariance is to be calculated.
336 # y: The other vector. x and y must have the same length, greater than one,
337 # with no missing values.
338 # verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
339 #
340 # Returns:
341 # The sample covariance between x and y.
342 n &lt;- length(x)
343 # Error handling
344 if (n &lt;= 1 || n != length(y)) {
345 stop("Arguments x and y have different lengths: ",
346 length(x), " and ", length(y), ".")
347 }
348 if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
349 stop(" Arguments x and y must not have missing values.")
350 }
351 covariance &lt;- var(x, y)
352 if (verbose)
353 cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
354 return(covariance)
355}
356</pre>
357
358<h4 id="todo">TODO Style</h4>
359
360<p>
361 Use a consistent style for TODOs throughout your code.
362 <br/><code>TODO(username): Explicit description of action to
363 be taken</code>
364</p>
365
366
367 <h3> Language </h3>
368
369 <h4 id="attach">Attach</h4>
370 <p> The possibilities for creating errors when using
371 <code>attach</code> are numerous. Avoid it.</p>
372 <h4 id="functionlanguage">Functions</h4>
373 <p> Errors should be raised using <code>stop()</code>.</p>
374 <h4 id="object">Objects and Methods</h4>
375 <p> The S language has two object systems, S3 and S4, both of which
376 are available in R. S3 methods are more interactive and flexible,
377 whereas S4 methods are more formal and rigorous. (For an illustration
378 of the two systems, see Thomas Lumley's
379 "Programmer's Niche: A Simple
380 Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
381 <a href="https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
382 https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf</a>.)
383 </p>
384 <p>Use S3 objects and methods unless there is a strong reason to use
385 S4 objects or methods. A primary justification for an S4 object
386 would be to use objects directly in C++ code. A primary
387 justification for an S4 generic/method would be to dispatch on two
388 arguments.
389 </p>
390 <p>Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and
391 vice-versa.
392 </p>
393
394
395 <h3>Exceptions</h3>
396
397<p>
398 The coding conventions described above should be followed, unless
399 there is good reason to do otherwise. Exceptions include legacy
400 code and modifying third-party code.
401</p>
402
403
404<h3>Parting Words</h3>
405
406<p>
407 Use common sense and BE CONSISTENT.
408</p>
409 <p>
410 If you are editing code, take a few minutes to look at the code around
411 you and determine its style. If others use spaces around their
412 <code>if </code>
413 clauses, you should, too. If their comments have little boxes of stars
414 around them, make your comments have little boxes of stars around them,
415 too.
416 </p>
417 <p>
418 The point of having style guidelines is to have a common vocabulary of
419 coding so people can concentrate on <em>what</em> you are saying,
420 rather than on <em>how</em> you are saying it. We present global style
421 rules here so people
422 know the vocabulary. But local style is also important. If code you add
423 to a file looks drastically different from the existing code around it,
424 the discontinuity will throw readers out of their rhythm when they go to
425 read it. Try to avoid this.
426 </p>
427
428 <p>
429 OK, enough writing about writing code; the code itself is much more
430 interesting. Have fun!
431 </p>
432
433
434 <h3>References</h3>
435
436 <p>
437 <a href="http://www.maths.lth.se/help/R/RCC/">
438 http://www.maths.lth.se/help/R/RCC/</a> - R Coding Conventions
439 </p>
440 <p>
441 <a href="http://ess.r-project.org/">http://ess.r-project.org/</a> - For
442 emacs users. This runs R in your emacs and has an emacs mode.
443 </p>
444
445 </body>
446
447</html>