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

[Steven Scott]

I agree with the consensus that documentation is for humans, while tests
are for computers.

On Thu, Jul 16, 2020, 8:41 PM <luke-tierney using uiowa.edu> wrote:

> 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
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]