Celda Development Coding Style Guide

Coding Style Guide

Following a particular programming style will help programmers read and understand source code conforming to the style, and help to avoid introducing errors (Programming style, Wikipedia).

R

Below is a list of guidelines on what is considered a good practice when writing R codes in celda pacakge. Most of them are adapted from Bioconductor - coding style or Google's R Style Guide. These guidelines are preferences and strongly encouraged!

• Indentation
  • Use 4 spaces for indenting. No tabs.
  • No lines longer than 80 characters. This includes function documentations, examples, and vignette code chunks.
• Assignment
  • Use <- not = for assignment.
• Variable names
  • Use camelCase.
• Function names
  • Use camelCase.
  • Do not use "." (in the S3 class system, some(x) where x is class A will dispatch to some.A).
  • Prefix non-exported functions with a ".".
• Class names
  • Use camelCase.
• File names
  • Use camelCase for regular ".R" file containing function definitions, e.g., celdaFunctions.R.
  • Filename extension for R code should be ".R". Use the prefix "methods-" for S4 class methods, e.g., methods-celdaS4.R. Generic definitions can be listed in a single file, AllGenerics.R, and class definitions in AllClasses.R.
• Use of space
  • Do not place a space before a comma, but always place one after a comma. This: a, b, c.
  • Always use space around “=” when using named arguments to functions. This: somefunc(a = 1, b = 2).
  • Place spaces around all binary operators +, -, *, /, ==, |, &, etc.
    • GOOD:

      tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
      total <- sum(x[, 1])
      total <- sum(x[1, ])
      

    • BAD:

      tab.prior <- table(df[df$days.from.opt<0, "campaign.id"])  # needs spaces around '<'
      tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"])  # needs a space after the comma
      tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"])  # needs a space before <-
      tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"])  # needs spaces around <-
      total <- sum(x[,1])  # Needs a space after the comma
      total <- sum(x[ ,1])  # Needs a space after the comma, not before
      

  • Place a space before left parenthesis, except in a function call.
    • GOOD:

      if (debug)
      return(vector)
      

    • BAD:

      if(debug) # needs a space before left parenthesis
      return (vector) # superfluous space before left parenthesis
      

  • Do not place spaces around code in parentheses or square brackets.
    • GOOD:

      if (debug)
      

    • BAD:

      if ( debug )  # No spaces around debug
      

  • Do not place spaces at the end of line
    • GOOD:

      # no space after 2
      a <- 1 + 2
      

    • BAD:

      # superfluous spaces after 2
      a <- 1 + 2   
      

• Curly Braces
  • An opening curly brace should never go on its own line; a closing curly brace should always go on its own line. Avoid omitting curly braces when a block consists of a single statement.
    • GOOD:

      if (is.null(ylim)) {
          ylim <- c(0, 0.06)
      }
      

      Always begin the body of a block on a new line.
    • BAD:

      if (is.null(ylim)) ylim <- c(0, 0.06) 
      if (is.null(ylim)) {ylim <- c(0, 0.06)}
      

  • Surround else with braces. An else statement should always be surrounded on the same line by curly braces.
    • GOOD:

      if (condition) {
          one or more lines
      } else {
          one or more lines
      }
      

    • BAD:

      if (condition) {
          one or more lines
      }
      else {
          one or more lines
      }
      

    • BAD:

      if (condition)
          one line
      else
          one line
      

• Comments
  • Entire commented lines should begin with # and one space. # some comment
  • Indent at the same level as surrounding code. For example:

    f1 <- function(a, b) {
        # indent comment at the same level as surrounding code!
        return(a + b)
    }
    

• Namespaces
  • Import all symbols used from packages other than “base”. Except for default packages (base, graphics, stats, etc.) or when overly tedious, fully enumerate imports.
  • Export all symbols useful to end users. Fully enumerate exports.
• End-User messages
  • message() communicates diagnostic messages (e.g., progress during lengthy computations) during code evaluation.
  • warning() communicates unusual situations handled by your code.
  • stop() indicates an error condition.
  • cat() or print() are used only when displaying an object to the user, e.g., in a show method or print(match.call()).

C/C++

To be added.