Lesson 17 of 17 · Week 09 · Thu Nov 19 · Tue Nov 24

Writing Good Software

Write code for people

Code is read many more times than it is written: by classmates reviewing it, by your instructor, and by you in three months. A computer runs messy code just as happily as clean code; people can't. This week is about habits that make your code easy to read, check and change.

Adapted from Software Carpentry's “Writing Good Software” episode (CC BY 4.0, The Carpentries). Text, examples and exercises have been rewritten for this course.

Structure a script

# clean-survey.R
# Reads the raw survey, fixes known data-entry problems, writes results/survey_clean.csv.
# Author: Ana Rojas, 2026-11-19

library(dplyr)                       # 1. packages at the top

raw <- read.csv("data/survey.csv")   # 2. read inputs (relative paths)

# 3. clean -------------------------------------------------------------
clean <- raw |>
  mutate(age = if_else(age == -99, NA, age))   # -99 means "not answered"

# 4. write outputs -----------------------------------------------------
write.csv(clean, "results/survey_clean.csv", row.names = FALSE)

A header saying what the script does, packages first, then input → processing → output. Comments explain why (“-99 means not answered”), not what. The code already says what. In Positron, a comment ending in four or more dashes becomes a section you can jump to from the outline.

Don't repeat yourself

Copy-pasted code is where bugs hide: you fix one copy and forget the others, or change a name in one place only. When you see the same lines twice, write a function (Week 05) and call it twice. Put numbers that mean something in named objects (kmh_per_knot <- 1.852) instead of repeating “magic numbers”.

Names and style

Follow one style consistently. This course uses the tidyverse style guide:

• Names in lower_snake_case that say what the thing is: life_exp_2007, not x2 or df1. Functions are verbs: standardize().
• <- for assignment; spaces around operators (x <- a + b) and after commas (f(x, y)); no space before the parenthesis in a function call.
• Lines under 80 characters; break long pipes after |>, one step per line.
• TRUE/FALSE, never T/F (those can be overwritten).

Positron can reformat a file for you (right-click → Format Document). It fixes spacing, but it can't choose good names.

Test your assumptions

stopifnot(nrow(clean) == nrow(raw))          # cleaning shouldn't drop rows
stopifnot(all(clean$age >= 0, na.rm = TRUE))

# a tiny test for a function: known inputs, known answers
stopifnot(isTRUE(all.equal(standardize(c(1, 2, 3)), c(-1, 0, 1))))

A test is code that stops loudly if something you believe is false. Put checks after each important step, and write a few tests with known answers for every function. Good tests fail on wrong code; a test that can't fail isn't testing anything. For larger projects, the testthat package organises tests.

Version control and reproducibility

• Git keeps the history of your project, so you can see what changed and go back. Positron's Source Control view (in the Activity Bar) lets you commit without the command line.
• Record your setup with sessionInfo() in reports, so others know which versions you used.
• Before you share: restart R, run your scripts from the top, and check that everything works. If it only works in your current session, it doesn't work.

Exercises

Each exercise gives you up to 10 checked attempts. Use Run as many times as you like to experiment first, then click Check answer when you're ready. Your exercises use numbers/subsets unique to you, so answers won't match a classmate's exactly.