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

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

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

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

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

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

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

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

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

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

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

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

--
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 at uiowa.edu
Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu

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