Plan for today

Programming Cafe

Good quality code is:

What is a style guide and why should I follow one?

A programming style guide consists of rules or guidelines on writing code. These can be seen as conventions or best practices for the community.

Following a style guide will make your code more consistent and readable, both for you and anyone who will interact with your code. It also reduces the chances of errors.

Some elements of style guides

Guidance of strategic use of whitespace and new lines:

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)

The second chunk is longer, but more modular and readable.

Some elements of style guides

Guidance on descriptive naming of functions and variables

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)

In the second chunk, we start functions with a verb and make variable names just long enough to be meaningful

What is a style guide and why should I follow one?

How can I start working with a style guide?

Most programming languages have style guides and these are followed by the community or enforced within organizations.

How can I start working with a style guide?

There are tools available to help you with this! You can use a linter and (auto)formatter while coding!

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.

Linters

Linters

The lintr package in R:

Linters

The lintr package in R:

(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.

(Auto)formatters

The styler package in R:

Your turn!

Try linting and formatting your own code!

Don’t have your own code? You can use our exercise files:

Linters & Formatters in R

Replace bad.R with the relevant script name.

Make sure you’re in the same working directory as the script!

install.packages(c("lintr", "styler"))

library(lintr)
library(styler)

lint("bad.R")

# you have two options for styler:

# style using a function

style_file("bad.R")

# or use the RStudio add-in (Addins drop-down menu -> Style active file)

Linters & Formatters in Python

Replace ‘pep8.py’ with the relevant script name if needed.

Make sure you’re in the same working directory as the script!

pip install flake8 black

flake8 pep8.py

black pep8.py