Comments in R: How to Comment Your Code (and Comment Out Blocks)

The # Symbol

A comment in R starts with #. From that character to the end of the line, R ignores everything:

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

Both placements are legal: a comment on its own line, or an inline comment after code. There is nothing to close - the comment simply ends where the line ends. One # is enough, and # inside a quoted string is just a character, not a comment:

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R Has No Multiline Comment

Here's the answer to the question every R beginner eventually googles: R has no block-comment syntax. There is no /* ... */, no """docstring""", no =begin/=end. Each commented line needs its own #. This is a deliberate simplicity in the language - and it's less painful than it sounds, because tooling fills the gap.

The real-world solution: your editor's toggle shortcut. In RStudio, select the lines and press Ctrl+Shift+C (Windows/Linux) or Cmd+Shift+C (macOS). Every selected line gets a # prefix; press it again and they're gone. This is what R programmers actually do, dozens of times a day, and it's worth committing to muscle memory this week. VS Code, Vim, and Emacs all have equivalent toggle-comment commands for R files.

The if (FALSE) trick. Because FALSE is never true, wrapping code in if (FALSE) { ... } guarantees it never runs:

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Know it, but treat it as a curiosity rather than a habit, because it has real caveats. The skipped code must still be syntactically valid R - a genuine block comment can hold anything, but if (FALSE) around a half-written line is a parse error that stops the whole script. It also silently changes meaning if the braces get edited. When you want lines disabled, the editor shortcut is safer; when you want them gone, delete them - that's what version control is for.

What Good Comments Say: Why, Not What

The code already says what it does. A comment that repeats it is noise that will eventually drift out of date and start lying:

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

The second comment carries information the code cannot: why the increment exists. That's the test for every comment you write - does it explain intent, context, or a non-obvious decision? Comments earn their keep on the weird lines: the workaround for a package bug, the off-by-one that's intentional, the formula that came from a specific paper. And remember the maintenance rule: when you change the code, change its comment, because a wrong comment is worse than none.

If you find yourself writing a comment to explain what a variable holds, often the better fix is a clearer name - see variables for that argument.

Section Headers That Fold in RStudio

Analysis scripts get long, and comments double as their table of contents. RStudio treats a comment line ending in four or more - (or = or #) as a section header:

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Each section becomes foldable and appears in RStudio's document outline, so a 300-line script turns into a navigable list of steps: load, clean, model, plot. Any of the trailing characters work as long as there are at least four; pick one style and keep it consistent. Even outside RStudio, section-header comments make a script's structure visible at a glance - it's the cheapest documentation an analysis can have.

roxygen2 Comments: #' in the Wild

Reading other people's R code - especially package source - you'll meet comments starting with #':

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

These are roxygen2 documentation comments. Written directly above a function definition, they're compiled by package tooling into the formal help pages you read with ?function_name. The tags (@param, @return) describe the function's inputs and output. To R itself, a #' line is an ordinary comment - the convention only has power inside the package-development toolchain. You don't need to write these until you build a package or document your own functions seriously; for now, just recognize them so package source code doesn't look mysterious.

What You Take Away

• # starts a comment; it runs to the end of the line, whether the line is all comment or code-then-comment.
• R has no multiline comment - toggle blocks with Ctrl/Cmd+Shift+C in RStudio, and reserve if (FALSE) {} for syntactically valid code you rarely skip.
• Comment the why, not the what - and update comments when the code changes.
• # Section name ---- comments give RStudio foldable sections and give readers a map of the script.
• #' lines are roxygen2 doc comments that become package help pages.

Next up: variables - creating them with <-, naming them well, and how R treats the values they hold.