Reproducibility

Aspects of good quality code

  • Readable
  • Reusable
  • Robust

Source: xkcd

Code readability: white space

Code is for computer, comments are for humans.

. . .

  • Use whitespace and newlines strategically.

. . .

Compare:

this <- function(arg1,arg2) res<-arg1*arg2;return(res)
hurts <- mean(c(this(3,4),this(3,1),this(9,9))); print(hurts)
this <- function(arg1,arg2){
  res <- arg1 * arg2
  return(res)
}

hurts <- mean(
  c(
    this(3,4),
    this(3,1),
    this(9,9)
    )
  )
print(hurts)

Code readability: names

  • use descriptive names for functions and variables
    • start functions with a verb
    • make variable names just long enough to be meaningful

. . .

Compare:

for i in my_shopping_basket:
  if(test(i)) > 10:
    purch(i)
  else:
    disc(i)
for item in basket:
  if(testNecessity(item)) > 10:
    purchase(item)
  else:
    discard(item)

Code readability: consistency

  • use a consistent style
    • consistency will make your code easier to understand and maintain
    • consult a styleguide for your language (keep conventions, and don’t reinvent the wheel)

. . .

Compare:

myVar<-original_variable+MOD(new.var)
my_var <- original_var + Modified(new_var)

Style guides

Source: xkcd

Linters

A linter is a static code analysis tool.

It will browse your code and flag/report issues (style, errors, bugs) as output. Then it’s up to the programmer to go through the list and fix the issues.

  • R: The lintr package

  • Python: There are several libraries, today we’ll use flake8

Linters: R

Function: lintr::lint(filename)

The lintr package in R:

Linters: Python

The flake8 library in Python:

Function: flake8 path/to/code/to/check.py

(Auto)formatters

While linters provide a report of issues, (auto)formatters will browse the code and correct issues automatically/directly.

The corrections will depend on the rules encoded within the package/library.

  • R: The styler package

  • Python: There are several libraries, today we’ll use black

(Auto)formatters: R

The styler package in R:

Function: styler::style_file(filepath)

(Auto)formatters: Python

The black library in Python:

Function:: black {source_file_or_directory}

Your turn

  • Run a linter through your code and identify style issues:

  • Edit your code to improve the style compatibility, based on the feedback from your linter.

  • Run an autoformatter through your code to automatically fix issues instead of simply flagging them:

  • If you find code that is hard to read, or variable names that need adjusting, make a note to work on it. Use #TODO or another consistent label so you can extract these notes later.

Workshop Computational Reproducibility