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

[Ben Bolker]

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

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