State of type validation (and advertisement) in R


#1

In keeping with defensive programming and input validation, I spend a lot of time enforcing and documenting types:

  • using Michel Lang’s checkmate::assert_* family and other predicates (checkmate is awesome and does double duty with testthat).
  • some semi-standardized language for the users such as #' @param x a character string, giving blah blah..

This works ok, but it always feels a little loose, and there’s some duplication in keeping the docs in line with the assertions.

I’ve just come across a couple of new cool ways of going about this:

  • standardized pseudo-code inside the documentation #' @param x [character(1)] giving blah blah.
  • @Gabor’s argufy which injects assertions and documentation based on special roxygen syntax
  • @jimhester’s types and typeCheck packages, which appear to be newer and do something similar, but based on special syntax in the function preamble and body not the docs (?).

Type annotation and validation seems like something that could save a lot of time in developing packages, and make the whole experience more rigorous for users (I spend so much time browsing docs to figure out what on earth some function requires for some argument …).

  • What are people’s thoughts on this?
  • Is (any of) this ready for prime time and/or still actively developed?
  • Is there some more documentation (vignettes)?

#2

argufy and types/typeCheck are definitely experimentations, at least right now they would need more work / testing to be generally useful I think.

At least in tidyverse packages we typically hand-write assertions, but using something like checkmate is also completely valid so if you are finding that useful I would continue with it. You can also pair it with #' @param x [character(1)] etc. to make it more clear to your users what the interface is.


#3

I’d also like to see a more standardized approach for type enforcement and documentation. I’m often confused about the return type from a function, and always thought it was strange how discretion is left to the author for the way they want to document this information.