title: "CPAT Project Style Guide" author: "Curtis Miller" date: "August 9, 2018" output: pdf_document: default html_document: default
This is a style guide for the project CPAT, a package implementing change point analysis tests. This document defines naming conventions, whitespace conventions, etc.
E
rather than e
in
the name)._
; .
should be
avoided, but exceptions can be made when the name is trying to signal its
relationship with other objects in R from other packages. For example,
functions that return htest
-class objects have names like t.test()
, so a
name like hr.test()
that returns a htest
-class object is appropriate.()
;
for example, mean()
._cpp
appended at the end._
, -
, or .
..R
; R Markdown and Seave files end in .Rmd
and .Rnw
,
resp.<-
for variable assignment; never use =
.Curly braces (that is, {}
) are placed in lines according to K & R style,
such as
r
f <- function(x) {
cat("x:", x)
}
;
should never be used to conclude a line. On occasion, it can be used to
separate statements that are very closely related and put on the same line,
such as y <- 1 + 1; cat("y:", y)
, but this should be a rare occurance and,
again, the statements should be short.
return()
should be used only when the function is terminating early....
if present.The only time require()
can be used is when it is it is used to check if a
package exists and install the package if it doesn't; for example,
r
if (!require("dplyr")) {
install.package("dplyr")
library(dplyr)
}
In all other contexts, packages should be loaded via library()
, and this
should never be done in a .R
file located in the /R
directory of the
package.
Code blocks should be properly indented to indicate what code is in a code block. More indenting and spacing can be used to make arguments, lists, etc. visually line up, making it easier to read. For example:
r
mat <- matrix(c(1, 1, 1,
1, 2, 3,
1, 3, 5), nrow = 3)
Function arguments in function definitions should not be defined on separate lines; they should use as few lines as possible. That said, function arguments should align in such a way that the first character of the first argument on each line aligns, causing the name of the function (and the accompanying parenthesis) has its own visual space. For example:
r
foo <- function(bar, baz = 2, # Other arguments not written...
fin = 10)
Operators such as <-
, +
, %*%
, etc. should be surrounded by spaces; for
example, y <- x + 1
, not y<-x+1
. This includes =
when it is being used
for assigning argument values, so f(foo = 7)
is fine, while f(foo=7)
is
not. The only exceptions are /
and ^
; it's appropriate and common to not
space these out.
if
statement, can be kept to one
line; otherwise, split up across lines.DESCRIPTION
, fields listing other relevant packages/software (such as
Depends
and Imports
) need to list each package (and relevant version
information) on its own indented line.When documenting, spacing should be such that the description of an argument aligns with itself, like so:
```r
```
Incomplete documentation should include TODO: WRITE DESCRIPTION
or a similar
TODO
statement.
Every .R
file needs to start with a description. The first line can be a
shebang for executable files. But this should be immediately followed by the
following:
```r
x <- 1 + 1 # First line of code ```
#
, followed by # TITLE
on a new
line, then another 80 #
.TODO
comments are to be inserted to show what further work needs to be done
in a document. For R scripts, they take the following format:
```r
```
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.