30 Side-effect soup
Side-effect soup occurs when you mix side-effects and regular computation within the same function.
30.1 What is a side-effect?
There are two main types of side-effect:
- those that give feedback to the user.
- those that change some global state.
30.1.1 User feedback
Signalling a condition, with
Printing to the console with
Drawing to the current graphics device with base graphics or grid.
30.1.2 Global state
Creating (or modifying) an existing binding with
Modifying the search path by attaching a package with
Changing the working directory with
Modifying a file on disk with (e.g.)
Changing a global option with
options()or a base graphics parameter with
Setting the random seed with
Installing a package.
Changing environment variables with
Sys.setenv(), or indirectly via a function like
Modifying a variable in an enclosing environment with
Modifying an object with reference semantics (like R6 or data.table).
More esoteric side-effects include:
Detaching a package from the search path with
Changing the library path, where R looks for packages, with
Changing the active graphics device with (e.g.)
Registering an S4 class, method, or generic with
Modifying the internal
30.2 What are some examples?
The summary of a linear model includes a p-value for the overall
regression. This value is only computed when the summary is printed: you can see it but you can’t touch it.
mod <- lm(mpg ~ wt, data = mtcars) summary(mod) #> #> Call: #> lm(formula = mpg ~ wt, data = mtcars) #> #> Residuals: #> Min 1Q Median 3Q Max #> -4.5432 -2.3647 -0.1252 1.4096 6.8727 #> #> Coefficients: #> Estimate Std. Error t value Pr(>|t|) #> (Intercept) 37.2851 1.8776 19.858 < 2e-16 *** #> wt -5.3445 0.5591 -9.559 1.29e-10 *** #> --- #> Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 #> #> Residual standard error: 3.046 on 30 degrees of freedom #> Multiple R-squared: 0.7528, Adjusted R-squared: 0.7446 #> F-statistic: 91.38 on 1 and 30 DF, p-value: 1.294e-10
30.3 Why is it bad?
Side-effect soup is bad because:
If a function does some computation and has side-effects, it can be challenging to extract the results of computation.
Makes code harder to analyse because it may have non-local effects. Take this code:
calculate()don’t have side-effects then you can predict what
dfwill be. But if
options(stringsAsFactors = FALSE)then
dfwould now contain a character vector rather than a factor.
Side-effect soup increases the cognitive load of a function so should be used deliberately, and you should be especially cautious when combining them with other techniques that increase cognitive load like tidy-evaluation and type-instability.
30.4 How avoid it?
30.4.1 Localise side-effects
Constrain the side-effects to as small a scope as possible, and clean up automatically to avoid side-effects. withr
30.4.2 Extract side-effects
It’s not side-effects that are bad, so much as mixing them with non-side-effect code.
Put them in a function that is specifically focussed on the side-effect.
If your function is called primarily for its side-effects, it should return the primary data structure (which should be first argument), invisibly. This allows you to call it mid-pipe for its side-effects while allow the primary data to continue flowing through the pipe.
30.4.3 Make side-effects noisy
Primary purpose of the entire package is side-effects: modifying files on disk to support package and project development. usethis functions are also designed to be noisy: as well as doing it’s job, each usethis function tells you what it’s doing.
But some usethis functions are building blocks for other more complex tasks.
30.4.4 Provide an argument to suppress
You’ve probably used
base::hist() for it’s side-effect of drawing a histogram:
But you might not know that
hist() also returns the result of the computation. If you call
plot = FALSE it will simply return the results of the computation:
xhist <- hist(x, plot = FALSE) str(xhist) #> List of 6 #> $ breaks : num [1:21] -5.5 -5 -4.5 -4 -3.5 -3 -2.5 -2 -1.5 -1 ... #> $ counts : int [1:20] 1 0 1 21 79 483 1606 4303 9196 15036 ... #> $ density : num [1:20] 0.00002 0 0.00002 0.00042 0.00158 ... #> $ mids : num [1:20] -5.25 -4.75 -4.25 -3.75 -3.25 -2.75 -2.25 -1.75 -1.25 -0.75 ... #> $ xname : chr "x" #> $ equidist: logi TRUE #> - attr(*, "class")= chr "histogram"
This is a good approach for retro-fitting older functions while making minimal API changes. However, I think it dilutes a function to be both used for plotting and for computing so should be best avoided in newer code.
30.4.5 Use the
An alternative approach would be to always return the computation, and instead perform the output in the
Of course ggplot2 isn’t perfect: it creates an object that specifies the plot, but there’s no easy way to extract the underlying computation so if you’ve used
geom_smooth() to add lines of best fit, there’s no way to extract the values. Again, you can see the results, but you can’t touch them, which is very frustrating!
30.4.6 Make easy to undo
If all of the above techniques fail, you should at least make the side-effect easy to undo. A use technique to do this is to make sure that the function returns the previous values, and that it can take it’s own input.
This is how
par() work. You obviously can’t eliminate those functions because their complete purpose is have global changes! But they are designed in such away that you can easily undo their operation, making it possible to apply on a local basis.
There are two key ideas that make these functions easy to undo:
They invisibly return the previous values as a list:
nnamed arguments, they can take a single named list:
(I wouldn’t recommend copying this technique, but I’d instead recommend always taking a single named list. This makes the function because it has a single way to call it and makes it easy to extend the API in the future, as discussed in Chapter 19)
Together, this means that you easily can set options temporarily.:
If temporarily setting options in a function, you should always restore the previous values using
on.exit(): this ensures that the code is run regardless of how the function exits.
30.5 Package considerations
Code in package is executed at build-time.i.e. if you have:
For mac and windows, this will record when CRAN built the binary. For linux, when the package was installed.
Beware copying functions from other packages:
Version of barfy might be different between run-time and build-time.
Introduces a build-time dependency.