structure.qmd

# Structure

## Implementation

## Interface

A function's interface describes how, independent of its internal implementation, that function interacts with the external world.

### Inputs

-   @sec-inputs-explicit: All inputs to a function should be explicit arguments.
    Avoid functions that suprise the user by returning different results when the inputs look the same.

-   @sec-important-args-first: Required arguments should come before optional arguments.

-   @sec-arguments-independent: Make arguments as orthogonal as possible.
    Avoid complex interdependencies.

#### Default values

-   @sec-required-no-defaults: the absence of a default value should indicate that an argument is required; the presence of a default value should indicate that an argument is optional.

-   @sec-enumerate-options: If a details argument can take one of a fixed set of possible strings, record them in the default value and use `match.arg()` or `rlang::arg_match()` inside the function.

-   @sec-def-magical: Default values should return the same answer when set directly.

-   @sec-defaults-short-and-sweet: Default values should be short.
    If you have a complex calculation, either use `NULL` or an exported function.

-   @sec-def-inform: If a default value is particularly important, as has non-trivial calculation, let the user know what it is.

-   @sec-def-user: Use `getOption()` to allow the user to set default values.

#### Dots

-   @sec-dots-after-required: `...` should be placed between the data and details arguments.

-   @sec-dots-data: don't use `...` just to save the user from typing `c()` (unless the function is purely for data structure creation).

-   @sec-dots-prefix: carefully consider if all other arguments need a `.` prefix in order to reduce the chance of spurious matches.

-   @sec-dots-inspect: when using `...` with S3 methods, or passing on to other functions that silently ignore mismatches, check that all inputs in `...` are evaluated.

### Output

-   @sec-out-invisible: functions called primarily for their side-effects should invisibly return a useful value.

### Errors

-   @sec-err-call: don't display the call when generating an error message.

-   @sec-err-constructor: if the same error is generated by multiple functions, you should extract it out into its own function, an **error constructor**.

### Side-effects

-   @sec-side-effect-soup: mixing side-effects and computation in a single function makes for functions that are hard to reason about and hard to program with.

-   @sec-spooky-action: if a function has side-effects, it should be constrained to lie at or beneath the current scope.