STAT 380 R Programming Style Guide

Rmd Document organization

• front-matter
  1. clean-up: rm(list = ls())
  2. source() and library() statements
  3. user-defined functions–e.g. anytime you use function()
  4. load all data used
• body of document including well-commented and well-organized code

Whitespace

• begin new line after ~80 characters (set up RStudio to draw reference line)
• begin new line after chain operators (e.g. %>%, +)
• blank lines are useful to separate command sequences just as paragraphs are used to separate sentence sequences:
  • before and after a sequence of chained commands
  • before and after a group commands unified toward some goal
• comments (use them!)
  • Entire commented lines should begin with # and one space
  • End of line comments
    • appended to line of code: precede with two spaces, #, and then one space
    • additional spacing can be used to align at the # in case of several end of line comments in close succession
• Modified “Advanced R” style for spacing (http://adv-r.had.co.nz/Style.html; see examples there)
  • Spaces around all infix operators including =, +, -, <-, etc., with exception of :, ::
  • Always put a space after a comma, and never before (as in English)
  • Place a space before left parentheses, except in a function call
  • Do not place spaces around code in parentheses or square brackets (unless there’s a comma, in which case see above).
• curly braces ({, })
  • An opening curly brace ({) should never go on its own line and should always be followed by a new line
  • A closing curly brace (}) should always go on its own line, unless it’s followed by else.
  • Always indent the code inside curly braces (and use progressive indenting for nested curly braces).

Object naming

• Always use <- assignment operator (never = for object assignment)
• Use CamelCase or Snake_case; Do not use periods “.” in object names (e.g., not.cool), because it can mess with R’s internal functions
• Avoid reusing object names
  • the same name should NOT refer to fundamentally different objects at different places in the same code script
  • do NOT choose names that coincide with popular functions (e.g. if you calculate a mean, name the object avg, NOT mean)
• Preferred capitalization
  • try to begin variable, vector, scalar names with lowercase letter
  • try to begin data set, list, array, matrix names with CAPITAL letter
  • don’t necessarily worry about renaming external objects that don’t follow convention

General suggestions

• minimize nested syntax where possible
  • Bad: Result <- select(filter(Data, condition), var1, var2)
  • Better: Result <- Data %>% filter(condition) %>% select(var1, var2)
  • Best:

    Result <- 
      Data %>%
      filter(condition) %>% 
      select(var1, var2)

• begin new line after comma for compound mutate and summarise statements
• always preserve access to the uncorrected/raw source data (i.e. never overwrite your only copy of the source data)

Resources & code examples (including good and bad):

• MDSR Textbook (they sometimes flag style suggestions as a “Pro Tip”)
• Google’s R Style Guide (https://google.github.io/styleguide/Rguide.xml)
• Hadley Wickham’s “Advanced R” Style Guide (https://google.github.io/styleguide/Rguide.xml)
• This document is the authority for our class when the style guides disagree (e.g. object naming)

https://xkcd.com/1513/