Each year I have the pleasure (actually it’s quite fun) of teaching R programming to first year mathematics and statistics students. The vast majority of these students have no experience of programming, yet think they are good with computers because they use facebook!

Debugging students' R scripts

The class has around 100 students, and there are eight practicals. In some of  these practicals  the students have to submit code. Although the code is “marked” by a script, this only detects if the code is correct. Therefore, I have to go through a lot of R functions by hand and find bugs.

• First year the course ran, I had no style guide.
  • Result: spaghetti R code.
• Second year: asked the students to indent their code.
  • In fact, during practicals I refused to debug in any R code that hadn’t been indented.
  • Result: nicer looking code and more correct code.
• This year I intend to introduce a R style guide based loosely on Google’s and Hadley’s guides.
  • One point that’s in my guide and not (and shouldn’t be) in the above style guides, is that all functions must have one and only return statement. I tend to follow the single return rule for the majority of my R functions, but do, on occasions, break it. The bible of code styling, Code Complete, recommends that you use returns judiciously.

R Style Guide

This style guide is intended to be very light touch. It’s intended to give students the basis of good programming style, not be a guide for submitting to cran.

File names

File names should end in .R and, of course, be meaningful. Files should be stored in a meaningful directory – not your Desktop!
GOOD: predict_ad_revenue.R BAD: foo.R

Variable & Function Names

Variable names should be lowercase. Use _ to separate words within a name. Strive for concise but meaningful names (this is not easy!)
GOOD: no_of_rolls BAD: noOfRolls, free
Function names have initial capital letters and are written in CamelCase
GOOD: CalculateAvgClicks BAD: calculate_avg_clicks , calculateAvgClicks
If possible, make function names verbs.

Curly Braces

An opening curly brace should never go on its own line; a closing curly brace should always go on its own line.

GOOD:
if (x == 5) {
  y = 10
}
RtnX = function(x) {
  return(x)
}
BAD:
RtnX = function(x)
{
  return(x)
}

Functions

Functions must have a single return function just before the final brace

GOOD:
IsNegative = function(x){
  if (x < 0) {
    is_neg = TRUE
  } else {
    is_neg = FALSE
  }
  return(is_neg)
}
BAD:
IsNegative = function(x) {
  if (x < 0){
    return(TRUE)
  } else {
    return(FALSE)
  }
}

Of course, the above function could be simplified to test = x < 0

Commenting guidelines

Comment your code. Entire commented lines should begin with # and one space.  Comments should explain the why, not the what.

What's missing

I decided against putting a section in on "spacing" , i.e. place spaces around all binary operators (=, +, -, etc.). I think thus may be taking style a bit too far for first year course.

Comments welcome!