Skip to content

style_guide.md

Latest commit

 

History

History
103 lines (89 loc) · 4.65 KB

style_guide.md

File metadata and controls

103 lines (89 loc) · 4.65 KB

Code Style Guide

Consistency is key!

R Style Guide

Main guide: tidyverse style guide

Below are more specific guidelines

Line length

  • use 4 spaces (not the tab character and not 2 spaces) to indent
  • do not exceed 80 characters per line
    • very helpful to be able to open windows side by side w/o scrolling
    • very helpful to be able to see the code in a terminal window (if needed)
  • functions hint: for long lines use this format (which can work with pipes too)
    long_function_name_that_never_ends(
        first_long_argument_name = 1,
        second_long_argument_name = 2,
    )

Comments and documentation

  • Always in English, please run a spell-checker
  • Explain Why not What (assume people know the programming language)
    • leave a space after the comment symbol, as in #

Naming

  • Watch The Naming of Ducks
  • Where the language and the previous code base allow, variable names should follow the pattern my_variable (no CamelCase, just use underscore)
    • This works for Python, R and SQL identifiers
  • Functions names should be verbs
    • except for math-line functions such as cos()
    • avoid get_ and set_ unless they are OO like methods
    • should fit on one page (if longer, think about creating a second function)
  • When using Hungarian notation, consider using the suffixes from purrr::, such as _dbl, _lgl, etc.
    • other suffixes:
      • _msk: mask for logical/selecting within a vector
      • _idx: index, as in var_idx <- which(var_msk)
      • _sp: spatial package
      • _mat: matrix
  • Table / collection / list names: singular or plural?
    • good subjective discussion
    • preference for singular
    • use singular for dataframes, SQL tables, ORM classes
    • use plural for vectors, e.g., customer_names

More style advices

  • Note the updated .Rproj options: do not save / load data; save history
  • Indent 4 space throughout (same for Python and SQL)
    • check Global, Project options, then modify each file as needed
    • when 4 spaces throughout, restart RStudio
  • All files must end with an empty line
    • check Global, Project options, then modify each file as needed
  • Do make use of code diagnostic Options> Code> Diagnostic> check all)
    • fix formatting as needed
  • The first line of the file is one line docstring, same as in Python (what is the file about)
    • please update all file
  • Third line: # !diagnostics suppress= for constants
  • Fourth, etc. line # !diagnostics suppress= for functions
  • Once the global constants are read, DO NOT modify them ever
    • why: image a multi-user shiny app where each user modifies the global constants
    • DB pools work because they are the same for all users
    • .USER_EMAIL does not work; we need session dependent reactives
  • Two spaces between functions or between observers
  • There should not be three empty lines anywhere
  • (preferable) Empty first line in function (after the title)
  • (preferable) Empty before the returned result in a function or event reactive
  • Functions and event reactives should always indicate what they return, even if it is NULL
    • df <- ... <new line>} works, but not recommended, it needs to end with df<new line>}
  • If using non-starndard evaluation, e.g. select(df, col1) in a function, at the begining of the function add col1 <- NULL
    • this stops CRAN checker from complaining that col1 is not found
    • resolves ambiguity about col1 and very likely to result in an error in dplyr if col1 is missing
  • When calling a function, start a new line after ( as in the duck video
  • When defining a function, keep the first arg on the first line, second arg on the second line
    • OK to keep everything on one line if 2-3 args
    • why: makes each arg standout; extra indentation helps to note the function definition
my_function <- function(
  arg1, arg2, arg3 = FALSE, arg4 = NULL) {

becomes

my_function <- function(arg1, 
                        arg2, 
                        arg3 = FALSE, 
                        arg4 = NULL) {
  • On each row, close as many parantes as you open in a few rows above
  • (preferable) When calling a function, if the arguments span several rows:
    • name the arguments
    • one argument per line
    • the closing paranthesis should be on a new line (preferable, where it helps)
  • Use one empty line inside functions to separate code sections
    • code comments also help visually + offer guidance