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

[Jeff Newmiller]

Looks like 187 opportunities to improve clarity.

On July 16, 2020 11:30:37 AM PDT, Ben Bolker <bbolker using gmail.com> 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
>
>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

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