Flip Project R Style Guide

From Displayr
Jump to: navigation, search

Code written for The flip Project should conform to this style guide. However, nothing in this style guide should be taken as the one-and-only "correct" way of writing code, but it is useful to have a consistent style when we are all sharing code and contributing to a common project. Though most code should attempt to adhere to these guidelines wherever possible when writing functions, any of these guidelines can be broken if it increases readability and understanding.

Assignment

Use <- and not =.

Good: x <- 5

Bad: x = 5

Indentation

4 spaces.

Spacing

Place spaces around all binary operators (=, +, -, <-, etc.), except ^, $ and :. Do not place a space before a comma, but always place one after a comma. Do not insert spaces between function names and their opening parentheses. Do place a space between language constructs (e.g. if, for) and their opening parentheses.

Curly braces

An opening curly brace should go on its own line, indented to the same level as the previous line. A closing curly brace should go on its own line, indented to the same level as its corresponding opening curly brace.

Test <- function(x, y)
{
    if (x > 0)
    {
        x <- log(x)
    }
    else
    {
        x <- x^2
    }
 
    return (x + y)
}

Variable and parameter names

Variable and parameters should be named using period.separated.lowercase.

In an attempt to enhance readability and reduce the need for documentation, write descriptive variable names and do not get too carried away by striving for very short line lengths. this.is.a.good.name and obj is not.

Standard parameter and variable names

Take care to use informative and consistent parameter names.

Definition Name
An object that is required to be of a particular class (e.g., if writing summary.MyFunction). MyClass.object
An R data.frame data, or, when disambiguation is required, variables
A variable in Q or an R data-frame variable
A variable in Q or an R data-frame variable
A string of text string
A matrix x, m

Exceptions

Exception: When creating a classed object, the function name (constructor) and class should match (e.g., lm).

Function names

Functions for widespread use

If a function is being written with the intent that a user may call it directly, it should be named using UpperCamelCase, e.g. LinearRegression. If this is in a package it should be added to the NAMESPACE file for the package, e.g. export(LinearRegression).

Functions that the end-user should not use

Where we write a function for use by other functions, it should be named using lowerCamelCase, e.g. myInternalFunction. These should not be exported from the package.

Functions within functions

If a function is within another function, it should be named using lowerCamelCase prefixed with a period, e.g. .myTestFunction <- function() ....

See also

Writing Functions for the flip Project Standard R

Acknowledgements

This document inherits from Google's R style guide.