4 Coding guidelines - CorrelAid/project-resources GitHub Wiki

To ensure that the project stays clean, consistent and easy to understand, please have a look at the following guidelines when writing code and adding new files to the repository. This will also make publication easier later on.

My suggestions are based on the Tidyverse styleguide. Below, I will just mention the most important guidelines you can follow to write consistent code in the project.

❗ Please note that the repository contains an automated code styling check using the lintr R package. The checks run automatically whenever there is a pull request. This way, we make sure that we have a consistent and best practice coding style and we can adjust our coding if the lintr checks complain about some of our code.

File names

Use descriptive file names that make it easy to understand what's going on in them
Avoid special characters or white space in file names
If the files follow a specific order, use numbers to sort them
Use lower case for file names

# good file names
1_clean_try_data.R
2_analyse_try_data.R

# bad file names
clean try data.R
Stuff.R

Code structure

Split code into multiple files

Instead of writing extremely long code files, consider if your code can be split into multiple files. You could for example create separate R files to define some utility functions and then source this script in the main script. This helps to avoid cluttering your script:

source("script_with_function_definitions.R")

Use section headers

Mark sections in your code using sections headers. This makes navigation much easier. You can either type a section heading (see example), or use the keyboard shortcut Ctrl/Cmd + Shift + R:

# This is a section heading -----------------------------------------------


# This is another section heading -----------------------------------------

You can use RStudio to navigate section headings by clicking on the document outline button next to the run button on the top right of your script.

Loading packages

Load all your packages in the beginning of the script in one block

Line length

Try to limit the length of your code lines to 80 characters. This is the standard line length that is nicely readable on most screens. By default, RStudio already places a vertical line in your script to help you find the 80 characters. If you don't see this line in your script, you can go to Tools -> Global Options -> Code -> Display -> Show margin.

Syntax

Object names

Object names should be lower case and snake case using _. E.g.

# Good
day_one
day_1

# Bad
DayOne
dayone

Paths

Always use relative instead of absolute paths. Since our repository is an RStudio project, all paths can be set relative to the project root. This makes sure that the code works on all our machines without any adjustments necessary. For example:

# good, will work on all machines
read.table("data/traits.txt") 
# bad, will only work on one machine
read.table("C:/Users/Selina/Docuemnts/trais.txt")

This also means that you do not need to put setwd() anywhere. Just put everything into the project and you can use relative paths to find it.

Named function arguments

Always match function arguments via names and not positions. An exception can be the first argument of a function because this is very often the data and does not have to be named necessarily.

# good
mean(x = data$some_col, na.rm = TRUE)
mean(data$some_col, na.rm = TRUE)
# bad
mean(data$some_col, TRUE)

Comments

Use comments to describe why you did something if you think that it will help people to better understand your code.

Use `styler`

The styler R package can be used to automatically format your code according to the tidyverse style guide. Then you don't need to take care of the formatting when typing code but you can let R do the work for you.

Just install the package with

install.packages("styler")

Then in R Studio you can go to Addins on top and you can find the option to style your active file automatically:

Use `lintr`

As I mentioned before, the lintr package will check the project automatically whenever there is a pull request on Github. If you want to make sure that your code passes this test, you can also run it locally before you push to Github. If lintr complains about some lines, fix them and push the fixes again to Github.

To do this, you need to install the lintr package:

install.packages("lintr")

Then you can lint your package by calling the following function in the console:

lintr::lint_dir()

Problems with your coding style are now shown to you in the console and you can click on them to jump to the respective lines and fix them.