[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, Ben Bolker wrote:

> FWIW/in defense of the OP, this is a *very* common idiom in the base R code 
> base.  There may be some false positives, but
>
>  find . -name "*.Rd" -exec grep -Fl "stopifnot(" {} \; | grep -v doc | wc
>
> lists 187 files, e.g. from src/library/utils/man/object.size.Rd

And I probably wrote some of them, but I don't think I would now.
As a rule, I think the documentation is clearer without the tests.

On the other hand, we don't all agree on these things.

>
> stopifnot(identical( ## assert that all three are the same :
>              unique(substr(as.vector(fsl), 1,5)),
>              format(round(as.vector(sl)/1024, 1))))
>
>
> On 7/16/20 2:02 PM, luke-tierney using uiowa.edu wrote:
>> 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
>>> 
>> 
>
> ______________________________________________
> 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