On 08/05/2019 7:16 a.m., Boris Steipe wrote:
Have you considered putting the explicit case into a comment? Something like ...
# For output to a CSV file, we would assign: myCSV <- "myResults.csv"
# ... but for this example we will use the value of tempfile() as the file name:
myCSV <- tempfile()
results <- doSomething(x, csvFile = myCSV, ...)
That seems like a good idea. If the lack of string literals in the
example was the issue, you might show the whole command in a comment
with a string literal:
# This would create "myResults.csv" in the current working directory:
# results <- doSomething(x, csvFile = "myResults.csv", ...)
# We will create a temporary file instead, with its name in myCSV...
myCSV <- tempfile()
results <- doSomething(x, csvFile = myCSV, ...)
I often find the lack of comments in examples less than optimal for didactic
reasons.
$0.02
Boris
On 2019-05-07, at 18:50, Duncan Murdoch <murdoch.dun...@gmail.com> wrote:
On 07/05/2019 6:44 p.m., Uwe Ligges wrote:
On 07.05.2019 19:57, Duncan Murdoch wrote:
On 06/05/2019 12:16 p.m., Jim Hester wrote:
For what it's worth, the recommendation to use `tempfile()` is very
confusing to R users.
Often users (particularly new users) jump directly to examples when
reading documentation and when you have these more complicated
examples they do not realize they can just use a simple string
literal.
See https://github.com/tidyverse/readr/issues/635 for an issue where
multiple users explicitly request examples which do _not_ use
`tempfile()`.
I think beginners rarely like the help pages, and that's really to be
expected: help pages need to be complete and correct, and beginners
really need a small subset of possibilities. Beginners need tutorials.
In the Github issue, you mentioned pollution of the working directory,
but I think a bigger problem is destruction of user data, e.g. if a user
has a file "wine.csv", and the example writes to that file.
So you need to do something to protect users. I think making examples a
little complicated by using setwd(tempdir()) with a literal filename, or
writing to tempfile() is worth it.
Thank you, Duncan. Well, setwd(tempdir()) should be made local to the
examples if used at all, as the user may not expect to have the working
directory changed.
Yes, I agree.
Duncan Murdoch
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
