Positional arguments in examples

[J-Savage]

This is more of a personal preference rather than an actual issue, but I think it could help users understand the code examples better.

The book (which is great by the way) seems to use a lot of arbitrary positional arguments in function calls mixed with keyword arguments. In general I really dislike using positional arguments: I find the code harder to read and interpret, particularly if you are not super familiar with the functions in question. Here is a simple example from Ch. 11.

  lm_models %>% 
  workflow_map("fit_resamples", 
               # Options to `workflow_map()`: 
               seed = 1101, verbose = TRUE,
               # Options to `fit_resamples()`: 
               resamples = ames_folds, control = keep_pred)
#> i 1 of 3 resampling: basic_lm
#> ✔ 1 of 3 resampling: basic_lm (2.9s)
#> i 2 of 3 resampling: interact_lm
#> ✔ 2 of 3 resampling: interact_lm (3s)
#> i 3 of 3 resampling: splines_lm
#> ✔ 3 of 3 resampling: splines_lm (4.4s)

Looking at this function, it is not immediately obvious what "fit_resamples" is. Copying the code into RStudio means you can quickly see the function documentation to find out what the arguments are, but looking at the text gives no indication of what it is. There are many more examples throughout the book.

Seeing the argument name makes it easier to understand how the function works, for me at least. I feel it would be helpful to use named arguments wherever possible, particularly when using functions for the first time.

[juliasilge]

Thanks for your feedback and for reading the book @J-Savage! 🙌

Typically our approach for using arguments by position is to do so in the cases outlined in Advanced R. You'll notice here we did this for obj (passed in first via the pipe) and fn. This is similar to command line tools and Python (and many other coding languages), where required arguments tend to be few in number and positional, while optional args can be more numerous and are usually named. There is a lot of gray here, of course (notice that fn is not required, for one), but overall we think we made the best choices we could for balancing conciseness, readability, and clarity.

Coding style preferences can be pretty personal so we don't claim to have achieved perfection or anything but we are happy with the norms we are using. 😄 Thank you again for the thoughtful reflection!

[github-actions[bot]]

This issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with a reprex: https://reprex.tidyverse.org) and link to this issue.