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

[iuke-tier@ey m@iii@g oii uiow@@edu]

On Thu, 16 Jul 2020, Henrik Bengtsson 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))

If the point is to communicate this to users I would write something like

## The following evaluates to TRUE:
add(1, 2) == sum(c(1, 2)

Using stopifnot just adds clutter that obscures the message for a
human reader; testthat::expect_equal even more so.

Best,

luke

>
> 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
>

-- 
Luke Tierney
Ralph E. Wareham Professor of Mathematical Sciences
University of Iowa                  Phone:             319-335-3386
Department of Statistics and        Fax:               319-335-3017
    Actuarial Science
241 Schaeffer Hall                  email:   luke-tierney using uiowa.edu
Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu