Home>

...

>

Commenting Guidelines

Commenting Guidelines

In this lesson, we will learn how to comment in R language.

Commenting Guidelines

Comment your code. Always. Your collaborators and future-you will be very grateful. Comments start with # followed by a single space and text of the comment.

# This is a comment.
  • Short comments can be placed after code preceded by two spaces, #, and then one space. For example,
  i <- i + 1  # Increment i
R
# GOOD
# Create histogram of frequency of campaigns by pct budget spent.
hist(df$pct.spent,
     breaks = "scott",  # method for choosing number of buckets
     main   = "Histogram: fraction budget spent by campaignid",
     xlab   = "Fraction of budget spent",
     ylab   = "Frequency (count of campaignids)")
# BAD
#Create histogram of frequency of campaigns by pct budget spent.
hist(df$pct.spent,
     breaks = "scott",#method for choosing number of buckets
     main   = "Histogram: fraction budget spent by campaignid",
     xlab   = "Fraction of budget spent",
     ylab   = "Frequency (count of campaignids)")
  • Comments should explain the why, not the what. Comments should not replicate the code by a plain langue, but rather explain the overall intention of the command.
R
# GOOD
  # define iterator
  i <- 1
    
# BAD
  # set i to 1
  i <- 1
  • Short comments can be placed on the same line of the code.
  • It makes sense to split the source into logical chunks by # followed by - or =.
R
# Read data
#---------------------------------------------------------------------------
    
# Tidy data
#---------------------------------------------------------------------------