4.12.1 Is my code correct?

Does it produce the desired output? This is pretty obviously important in principle, but it can be difficult to be sure that your code is correct. This is especially difficult if your codebase is large and complicated as it tends to become over time. While simple trial and error is an effective first approach, a more reliable albeit time- and thought-intensive strategy is to write explicit tests for your code and run them regularly.

4.12.2 Does my code follow the DRY principle?

Don’t Repeat Yourself (DRY) is a powerful and helpful strategy to make your code more reliable. This typically involves identifying common patterns in your code and moving them to functions or objects.

4.12.3 Did I choose concise but descriptive variable and function names?

Variable and function names should be descriptive when necessary and not too long. Try to put yourself in the shoes of someone who is reading your code for the first time and see if you can figure out what it does. Better yet, offer to buy a friend a coffee in return for them looking at it!

4.12.4 Did I use indentation and naming conventions consistently throughout my code?

Consistently formatted code is much easier to read (and possibly understand) than inconsistent code. Consider the following code example:

calcVal <- function(x, a, arg=2) { return(sum(x*a)**2)}
calc_val_2 <- function(x, a, b, arg) {
res <- sum(b+a*x)**arg
return(res)}

This code is inconsistent in several ways:

• naming conventions - calcVal is camel case, calc_val_2 is snake case
• new lines and whitespace - calcVal is all on one line, calc_val_2 is on multiple lines
• unhelpful indentation - calc_val_2 has a function body that is not indented, and the close curly brace is appended to the last line of the body
• unhelpful function and argument names - the function names describe very little about what the functions do, and the argument names x, a, etc are not very descriptive about what they represent
• unused function arguments - the arg argument in calcVal isn’t used anywhere in the function
• the two functions appear to do something very similar and could be made simpler using a default argument

A more consistent version of this code might look like:

exponent_product <- function(x, a, offset=0, arg=2) {
  return(sum(offset+a*x)**arg)
}

This code is much cleaner, more consistent, and easier to read.

4.12.5 Did I write comments, especially when what the code does is not obvious?

Sometimes what a piece of code does is obvious from looking at it:

x <- x + 1

Clearly this line of code takes the value of x, whatever it is, and adds 1 to it. However, it may not be obvious why a piece of code does what it does. In these cases, it may be very helpful to record your thinking about a line of code as a comment:

# add 1 as a pseudocount
x <- x + 1

Then when you or someone else reads the code, it will be obvious what you were thinking when you wrote it. In your career, you will encounter situations where you need to figure out what you were thinking when you wrote a piece of code. Endeavor to make future you proud of current you!

4.12.6 How easy would it be for someone else to understand my code?

If someone else who has never seen my code before is asked to run and understand it, how easy would it be for them to do so?

4.12.7 Is my code easy to maintain/change?

This is related to the previous question, but is distinct in that understanding what code does is just the first step in being able to make desired changes to it.

4.12.8 The styler package

Consistently formatted code is generally much easier to read than inconsistently formatted code. Consistent formatting may also allow you to identify syntax and logic errors much more easily than it might be otherwise. The styler package is an R package that can automatically format your code to make it consistent in a number of ways, including indentation, code block conventions and more. When you install styler with install.packages("styler") in RStudio, a new entry is available in the Addins menu:

styler Addin menu

These Addins allow you to let styler format your code for you according to some reasonable (albeit arbitrary) conventions.