The R programming language gets a lot of love for its powerful libraries and elegant approach to data manipulation. However, there’s more to using a language than simply putting a basic script together. It’s true that R is often approached from a utilitarian angle. You’ll often simply whip up an R script to handle a specific data set without any intent to reuse the code at a later date. But R is just as often found at the heart of long projects which might run for years or even decades. These larger projects need more than logical design. They also call for proper formatting and upkeep. And comments are one of the most important foundational elements of these tasks. But with that in mind, what is the best approach to comment management in R?
Commenting Basics
It’s important to first define comments as a general concept before we move on to the specifics of R comments. If you’ve used any programming language before then you’ve probably encountered comments. They’re text within source code that’s meant for programmers to read rather than an interpreter, compiler, or end-user. Comments are most commonly used to explain why specific techniques are used or to warn against changing certain elements. You might even use comments to alert future programmers about the physical location of backups when using data from written materials.
Of course, there’s also the unfortunately common comment that will warn people about issues with a particular piece of code. Most programmers dread encountering comments that essentially warn about code blocks that seem to work but that the author doesn’t fully understand. Those sorts of comments are, at best, a reminder to rewrite the code at a later date. But it’s not uncommon for those code-based black boxes to drift through an office without ever being touched.
The “don’t understand, fix later” comments often become both an inside joke and a dire warning. If you ever write a comment like that it’s imperative that you actually do follow up on the promise to fix it later. A “black box” in your code can become a serious source of code rot in the future if it’s not taken care of. And specifically by the person who wrote it in the first place.
Comments are best used to help other people rather than as a way to shift your work onto others. Comments are also generally best used under the rule that pithiness is king. Comments should be kept short and to the point. Likewise, you should always ask yourself if the comment is necessary or not. Does it add to the readability of your code or detract from it? An occasional explanatory comment can be invaluable. But if you have too many comments your code can become somewhat lost within it.
Of course, you might assume that you already know everything there is to know about comments. They’re typically seen as one of the most basic parts of a programming language. After all, the whole point of a comment is that they’re ignored by the programming language’s interpreter or compiler as it works through your source code. There doesn’t seem to be any pressing need to understand complex syntax or tricks when using comments. But as with many elements of programming, appearances can sometimes be deceiving. The hidden complexity of comments comes from the fact that most programming languages put their own spin on them. And individual IDEs often change how we work with comments.
Common Comment Concepts
We can begin looking at how to comment in R with one of the most common and easily used concepts. Take a look at the following code.
deltaOne <- data.frame(
a = c (5,10,15,20,25),
b = c(30,35,40,45,50),
c = c(55,60,65,70,75))
for (x in 1:nrow(deltaOne)){
for (y in 1:ncol(deltaOne)){
print(paste(deltaOne[x,y]))
print(deltaOne[x,y] + deltaOne[1,1])
}
}
This is far from the most complex code in the world. But you can probably see that we have some issues with how it’s laid out. The variable names aren’t descriptive, the purpose of the loop isn’t clear, and if this concept was taken much further it’d become exponentially convoluted. Now, look at how we can improve it with some comments.
deltaOne <- data.frame(
a = c (5,10,15,20,25),
b = c(30,35,40,45,50),
c = c(55,60,65,70,75))
#Our first comment
#Create the top of our loop using the rows in the deltaOne data frame
for (x in 1:nrow(deltaOne)){
#Create the inner loop using the columns in the deltaOne data frame
for (y in 1:ncol(deltaOne)){
#Print out the value of our deltaOne dataframe using the current values for row and column
print(paste(deltaOne[x,y]))
#We should grab the additive number from the data frame rather than explicitly stating it
#print(deltaOne[x,y] + 5)
# Now we add the current iteration value to 5, the first value in our data set
print(deltaOne[x,y] + deltaOne[1,1])
}
}
This code is far easier to read thanks to the fact that we’re using comments. Specifically, we’re using a single line comment style. These are the easiest comments to use in R as we simply need to type the # character. Note that while our comments might look like a string, the interpreter isn’t defining them or even seeing them.
Anything following the # on the same line is ignored by the R interpreter. We can even make the interpreter ignore code by redefining it as a comment. In this code sample, we skip over the line of code that uses 5 directly instead of grabbing it from the data frame. We can even comment out package import statements. This practice is useful if we’re trying to determine whether we’re actually using the functionality found in an imported package.
These single line comments are easy to use. But if you’ve used other programming languages then you might be wondering how to expand comments into a multiline comment style. This is possible in R, and extremely useful for a larger code block or R program. But it’s not quite as easy to make entire fields a comment in R as in some other languages.
From One to Many Lines
A one line comment is fine for a quick note. But you can probably imagine hundreds of situations where you might want to write out more complex concepts. Some programming languages use opening and closing symbols to make it easy to write out larger comments. Think of them as similar to opening and closing tags in HTML. But R, unfortunately, doesn’t have a built-in block comment system that would make it easy to comment over multiple lines.
We can manually comment out every line when we’re writing out a more complex explanation. But when we’re writing a larger program rather than a quick script we’re also usually making use of an IDE. And IDEs will typically provide us with a keyboard shortcut to comment out multiple lines with a single hotkey combination. For example, RStudio and Posit Cloud are among the most popular IDEs for R coding. And if you’re using them then you can simply select multiple lines of text and press ctrl-shift-c on your keyboard. This will turn any selected text into a comment even if you’ve selected multiple lines. And the reverse is true as well. If you select a commented line and press those keys then the IDE will uncomment it.