[R-pkg-devel] Interpret feedback: not write testthat-tests in examples

[Jeff Newmiller]

The point of an example is to provide an illustration of how the function should be used for people who are not software developers. IMO any use of any other functions should be absolutely minimized to reduce the cognitive overload ("you need to understand 13 other concepts before you can understand what this function does"). Even stopifnot is in my view best avoided, and if you choose to use it then the use of that function should come _after_ the use of the function so it can be ignored by the reader without disrupting their reading of the example.

Complex interactions between functions should be described in vignettes, and tests should be stored in test code. R package help already has a reputation for being obtuse to beginners and mixing tests into examples exacerbates that perception.

On July 16, 2020 10:39:45 AM PDT, Henrik Bengtsson <henrik.bengtsson using gmail.com> wrote:
>If the point of having, say,
>
>stopifnot(add(1, 2) == sum(c(1, 2))
>
>is to make it explicit to the reader that your add() function gives
>the same results as sum(), then I argue that is valid to use in an
>example.  I'm pretty sure I've used that in some of my examples.  For
>the purpose, there should be no reason why you can't use other
>"assert" functions for this purpose, e.g.
>
>testthat::expect_equal(add(1, 2), sum(c(1, 2))
>
>Now, if the point of your "assert" statement is only to validate your
>package/code, then I agree it should not be in the example code
>because it adds clutter.  Such validation should be in a package test.
>
>So, if the former, I suggest you reply to the CRAN Team and explain
>this.
>
>/Henrik
>
>On Thu, Jul 16, 2020 at 6:28 AM Richel Bilderbeek
><richel using richelbilderbeek.nl> wrote:
>>
>> Dear R package developers,
>>
>> I would enjoy some help regarding some feedback I got on my package
>from a CRAN volunteer, as I am unsure how to interpret this correctly.
>>
>> This is the feedback I got (I added '[do]'):
>>
>> > Please [do] not write testthat-tests in your examples.
>>
>> I wonder if this is about using `testthat` or using tests in general.
>>
>> To simplify the context, say I wrote a package with a function called
>`add`, that adds two numbers. My example code would then be something
>like this:
>>
>> ```
>> library(testthat)
>>
>> expect_equal(add(1, 2), 3)
>> ```
>>
>> The first interpretation is about using `testthat`: maybe I should
>use base R (`stopifnot`) or another testing library (`testit`) or
>hand-craft it myself?
>>
>> The second interpretation is about using tests in example code. I
>like to actively demonstrate that my code works as expected. I checked
>the policies regarding examples, and I could not find a rule that I
>should refrain from doing so.
>>
>> What is the correct response to this feedback?
>>
>> Thanks for your guidance, Richel Bilderbeek
>>
>> ______________________________________________
>> R-package-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>______________________________________________
>R-package-devel using r-project.org mailing list
>https://stat.ethz.ch/mailman/listinfo/r-package-devel

-- 
Sent from my phone. Please excuse my brevity.