Chapter 6: R Comments
1. What are Comments in R? (The Simple Truth)
Comments are notes you write inside your code that the computer completely ignores. R never reads or executes them — they’re only for humans (you, your teammates, your future self, or your professor checking your project).
Main purposes:
- Explain why you wrote something (the intention / business logic)
- Make code easier to read & understand later
- Temporarily disable lines during testing/debugging
- Add section headers / TODO notes / references
2. The Only Syntax Rule in R for Comments (Very Simple!)
In R, everything after a # (hash/pound sign) on the same line is a comment → ignored by R.
R
|
0 1 2 3 4 5 6 7 8 9 10 11 |
# This entire line is a comment – R skips it completely temperature <- 29.5 # Hyderabad temp right now (Feb 2026) – this is an inline comment # You can put # anywhere after code mean(marks) # calculate average score |
Key facts (memorize these!):
- # must be at the start of a comment (or after code on the same line)
- No multi-line comment like /* */ in C/Java or “”” in Python → only single-line with #
- To comment multiple lines → put # at the beginning of each line
- In RStudio: Ctrl+Shift+C (Windows/Linux) or Cmd+Shift+C (Mac) → toggles comment on selected lines (super handy!)
3. Real Examples – Let’s See Them in Action
Example 1: Basic explanatory comments
R
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# Load required packages (only run once if not installed) # install.packages(c("dplyr", "ggplot2")) # commented out so it doesn't reinstall every time library(dplyr) # For data manipulation (filter, select, mutate, etc.) library(ggplot2) # For beautiful plots # Read our sales data from CSV file sales <- read.csv("monthly_sales_hyd_2026.csv") # Quick look at first few rows head(sales) |
Example 2: Inline comments (explaining tricky parts)
R
|
0 1 2 3 4 5 6 7 8 |
# Convert temperature from Celsius to Fahrenheit # Formula: F = C * 9/5 + 32 fahrenheit <- celsius * 9/5 + 32 # apply element-wise (vectorized – no loop needed!) |
Example 3: Section headers (very common in long scripts)
R
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
# ============================================================================= # 1. DATA IMPORT & CLEANING # ============================================================================= data_raw <- readxl::read_excel("survey_data.xlsx", sheet = "Responses") # Remove incomplete rows data_clean <- data_raw |> filter(complete.cases(.)) # ============================================================================= # 2. EXPLORATORY ANALYSIS # ============================================================================= summary(data_clean$age) # ============================================================================= # 3. VISUALIZATION # ============================================================================= ggplot(data_clean, aes(x = age, fill = gender)) + geom_histogram(position = "dodge", bins = 15) + theme_minimal() + labs(title = "Age Distribution by Gender - Hyderabad Survey 2026") |
Example 4: Debugging / Testing (temporary comments)
R
|
0 1 2 3 4 5 6 7 8 |
# old_slow_way <- for(i in 1:nrow(df)) { ... } # too slow – replaced with vectorized version result <- df |> mutate(profit = revenue - cost) # fast & readable |
Example 5: TODO / FIXME notes (professional habit)
R
|
0 1 2 3 4 5 6 7 8 9 10 |
# TODO: Replace hardcoded path with user input or config file filepath <- "D:/Projects/data/raw/iris_extended.csv" # FIXME: Check why some NA values appear after join – possible key mismatch? joined <- left_join(students, marks, by = "student_id") |
4. Modern Best Practices for Comments in R (2026 Style)
From tidyverse style guide, R community, books like “The Art of Readable Code”, and recent advice:
| Rule / Tip | Why it matters | Good Example | Bad Example (avoid) |
|---|---|---|---|
| Explain WHY, not WHAT | Good code already shows WHAT – comments should explain intention / trade-offs | # Use log-transform because data is right-skewed (confirmed by skewness test) | # Take log of x (obvious from code) |
| Keep comments up-to-date | Outdated comments are worse than no comments – misleading | Update when you change logic | # Add 5 to each (but code now adds 10) |
| Use them sparingly | Too many comments = visual noise – aim for self-documenting code | Name variables clearly → fewer comments needed | Commenting every single line |
| Use complete sentences | Easier to read, looks professional | # Calculate monthly growth rate as percentage change from previous month. | # growth rate |
| Put file-level / script header | At top: purpose, author, date, dependencies | See header example below | No header → hard to know what script does |
| Use roxygen2 for functions/packages | Automatic help files + documentation | For packages/functions (we’ll cover later) | Plain # comments inside package functions |
| Separate sections clearly | Use # ==== or # —- for visual blocks | Shown in example 3 above | No separation in long scripts |
Recommended script header (copy this style!)
R
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# ============================================================================= # Project: Customer Churn Analysis - Hyderabad Retail 2026 # Author: Webliance # Date: February 17, 2026 # Description: Clean data, explore patterns, build simple logistic model # Packages: tidyverse, broom, ggplot2 # Input: churn_data.csv # Output: churn_report.html + model_summary.csv # ============================================================================= |
5. Quick Practice – Improve This Messy Code with Comments
Bad version (no comments):
R
|
0 1 2 3 4 5 6 7 8 9 |
x <- read.csv("data.csv") x <- x[!is.na(x$score),] m <- mean(x$score) print(m) |
Better version (good comments):
R
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Load raw survey responses collected in Jan-Feb 2026 raw_data <- read.csv("data.csv", stringsAsFactors = FALSE) # Remove rows with missing scores (incomplete responses) clean_data <- raw_data[!is.na(raw_data$score), ] # Calculate average score for valid responses only average_score <- mean(clean_data$score) cat("Average student score:", round(average_score, 1), "\n") |
See how much clearer it becomes?
Final Thoughts from Your Teacher
- Good comments = kindness to your future self (you’ll thank yourself in 6 months!)
- Bad/over comments = noise (train yourself to write clear variable names & functions first)
- In RStudio: comments appear in gray/different color → easy to spot
- Shortcut love: Ctrl+Shift+C to comment/uncomment blocks quickly
Ready for next step?
- Want to practice writing a commented mini-script together?
- Move to R vectors or data frames in detail?
- Or learn roxygen2 comments for functions?
Just tell me — whiteboard is ready! ☕📝🚀
