Comments - what to

1 Meaningful comments

What comments would be relevant here?

Question

Suggest comments for this code… think ‘what’ and ‘why’

# 1
d <- read.csv("my_data_file.csv")

# 2
d <- d %>% filter(id != "241269-1212")

# 3
d <- d %>% 
  mutate(s=factor(c("F", "M"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2 + 1 ])

Solution

Suggestions for meaningful comments

# ?? comments necessary ??
d <- read.csv("my_data_file.csv")

# excluded as participant entered an invalid CPR number
d <- d %>% filter(id != "2321369-1212")

# set 's' to F(emale) or M(ale) depending on odd/even id number in CPR
d <- d %>% 
  mutate(s=factor(c("M", "F"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2])

Notes for the solution

In relation to each of the three lines of code in the exercise above:

1. it is unnecessary to comment this line – the code is self-explanatory
2. it’s a good idea to comment line two to explain why the CPR number in question was deleted.
3. it’s a good idea to comment line three to explain what the code does, as it is not self-explanatory!

The code in line 3 is a little complicated (on purpose), but basically, it creates a new variable s which is either ‘M’ or ‘F’ for odd and even CPR numbers. If you want to understand the code:

If id is a text string representation of a CPR number, the code evaluates the last character in the string (substr(id,nchar(id),nchar(id))), converts it into a numerical value (as.numeric) and calculates the modulus 2 (%% 2), i.e. the integer remainder of division by 2 (which becomes 0 for even numbers and 1 for odd numbers), it then adds 1 (+1) and uses that numbers (which is now 1 for even CPR numbers and 2 for odd CPR numbers), and sets s to be index 1 or 2 of the factor factor(c("F", "M")) – this works just fine, but it is not self-explanatory, is it?

1.1 Commenting your code

Main points

• Always comment your code
• Comments should explain your thinking : ‘why’
• With good code the ‘how’ is self-evident
  • ..but if your code can not be self-evident: explain in comments