What convention for option names should be used?

[Torvaney]

As with much of base R, the style for global option names is inconsistent. To take a few examples from the documentation:

add.smooth
askYesNo
matprod
PCRE_limit_recursion

Within RStudio-adjacent packages, there seems to be a mix of styles (see discussion here)

Jenny Bryan suggests using package.option_name as a standard.

Is it worth adding this to the official style guide, for reference, going forward?

[hadley]

@lionel- what do you think of this naming scheme? Should be moving towards pkg_option?

cc @jennybc

[hadley]

Or even pkg::option_name?

[jennybc]

I don't have strong opinions but it would be nice if we happen to choose one of the conventions we are already using 🙂 then at least some of our actual option names will be compliant.

I do have a modest preference for pkg.descriptive_name. In general I like to use delimiters in a way that at least notionally supports parsing. So: split on . to separate package from option name, then _ separates words.

[lionel-]

@lionel- what do you think of this naming scheme? Should be moving towards pkg_option?

I think it'd be better if we had the same soft-namespacing convention everywhere, e.g. for S3 classes and attributes. Whereas dots are ok for options, they wouldn't be ok for S3 classes. For this reason I have a preference for underscore.

Or even pkg::option_name

I like that but the problem is that it forces quoting the name, which might be user-unfriendly.

[hadley]

@jennybc given the inability to use . everywhere, are you ok with _?

[jennybc]

I can let go of my scheme and to with _. I just wanted there to be a reason (and the S3 class rationale makes sense to me).

[salim-b]

Any news on this, i.e. did you make a final decision yet?

If you cannot use ., a possible convention to tell general and package-specific options apart (i.e. determine if an option is only meant to be relevant for a certain pkg) would be to just prepend pkg_[PKGNAME]_ to the option name. So usethis.description would become pkg_usethis_description. This would be sufficiently semantic to allow (notional) parsing I guess.

[krlmlr]

Did we decide on a syntax here?

[lionel-]

There was an internal poll on Slack where the favourite style was pkg.option. It looks like we are going to use the dot separator though we didn't formally discuss this yet.

[luciorq]

It is good to have a formalization, at least.

So, the standard for a multi-word option name would be pkg.option_name, right?

[hadley]

I think we might need to reconsider the option naming scheme if we're thinking of providing a wrapper like pkg_options$foo. Then it's no longer so important to avoid the . in the name.

[lionel-]

Would pkg_options be an environment of options (perhaps with a special class for printing)? I think I like that idea a lot.

• Provides a documentation anchor for discovering all options defined in a package.
• More efficient than the pairlist of global options (see below).
• Allows active bindings when the default depends on some other state.
• There may be both exported and non exported option environments. This makes it clear what's internal and what's not.

On the downside, local_options(foo = bar) is terser than local_bindings(pkg_options, foo = bar), though the latter is not too bad.

foo <- structure(as.environment(options()), class = "foo")

bench::mark(
  foo$width,
  getOption("width"),
  iterations = 10e4
)
#> # A tibble: 2 × 13
#>   expression           min median `itr/sec` mem_alloc `gc/sec`  n_itr
#>   <bch:expr>         <bch> <bch:>     <dbl> <bch:byt>    <dbl>  <int>
#> 1 foo$width              0   83ns  4738650.        0B     47.4  99999
#> 2 getOption("width") 333ns  458ns  2050965.        0B      0   100000