Add bit on comments

workflow-basics.Rmd

@@ -39,7 +39,8 @@ primes - 1
 
 All R statements where you create objects, **assignment** statements, have the same form:
 
-```{r eval = FALSE}
+```{r}
+#| eval: false
 object_name <- value
 ```
 
@@ -57,7 +58,26 @@ R will ignore any text after `#`.
 This allows to you to write **comments**, text that is ignored by R but read by other humans.
 We'll sometimes include comments in examples explaining what's happening with the code.
 
-TODO: add more info
+Comments can be helpful for briefly describing what the subsequent code does.
+
+```{r}
+# define primes
+primes <- c(1, 2, 3, 5, 7, 11, 13)
+
+# multiply primes by 2
+primes * 2
+```
+
+With short pieces of code like this, it might not be necessary to leave a command for every single line of code.
+But as the code you're writing gets more complex, comments can save you (and your collaborators) a lot of time in figuring out what was done in the code.
+
+However, ultimately, *what* was done is possible to figure out, even if it might be tedious at times, as the code is self-documenting.
+However, remembering or figuring out *why* something was done can be much more difficult, or impossible.
+For example, `geom_smooth()`, which draws a smooth curve to represent the patterns of the data has an argument called `span`, which controls the "wiggliness" of the smoother with larger values for `span` yielding a smoother curve.
+The default value of this argument is 0.75.
+Suppose you decide to change the value of `span`, and set it to 0.3.
+It would be very useful to add a comment noting why you decided to make this change, for yourself in the future and others reviewing your code.
+In the following example the first comment for the same code is not as good as the second one as it doesn't say why the decision to change the span was made.
 
 ## What's in a name?
 
@@ -92,7 +112,7 @@ Ooops, you made a mistake!
 `this_is_a_really_long_name` should have value 3.5 not 2.5.
 Use another keyboard shortcut to help you fix it.
 Type "this" then press Cmd/Ctrl + ↑.
-That will list all the commands you've typed that start those letters.
+That will list all the commands you've typed that start with those letters.
 Use the arrow keys to navigate, then press enter to retype the command.
 Change 2.5 to 3.5 and rerun.