function-names.qmd

# Function names

```{r}
#| include = FALSE
source("common.R")
```

Follow the style guide (i.e. use `snake_cake`).

## Nouns vs verbs

In general, prefer verbs.
Use imperative mood: `mutate()` not `mutated()`, `mutates()`, or `mutating()`; `do()` not `did()`, `does()`, `doing()`, `hide()` not `hid()`, `hides()`, or `hiding()`.

Exception: noun-y interfaces where you're building up a complex object like ggplot2 or recipes (verb-y interface in ggvis was a mistake).

Nouns should be singular (`geom_point()` not `geom_points()`), simply because the plurisation rules in English are complex.

## Function families

Use prefixes to group functions together based on common input or common purpose.
Prefixes are better than suffixes because of auto-complete.
Examples: ggplot2, purrr.
Counter example: shiny.

Not sure about common prefixes for a package.
Works well for stringr (esp. with stringi), forcats, xml2, and rvest.
But there's only a limited number of short prefixes and I think it would break down if every package did it.

Use suffixes for variations on a theme (e.g. `map_int()`, `map_lgl()`, `map_dbl()`; `str_locate()`, `str_locate_all()`.)

Strive for thematic unity in related functions.
Can you make related fuctions rhyme?
Or have the same number of letters?
Or similar background (i.e. all Germanic origins vs. French).

## Length

Err on the side of too long rather than too short (reading is generally more important than writing).
Autocomplete will mostly take care of the nuisance and you can always shorten later if you come up with a better name.
(But hard to make long later, and you may take up a good word that is a lot of work to reclaim later).

Length of name should be inversely proportional to frequency of usage.
Reserve very short words for functions that are likely to be used very frequently.

## Conflicts

You can't expect to avoid conflicts with every existing CRAN package, but you should strive to avoid conflicts with "nearby" packages (i.e. packages that are commonly used with your package).

## Techniques

-   Thesaurus
-   List of common verbs
-   Rhyming dictionary

## Other good advice

-   [I Shall Call It.. SomethingManager](https://blog.codinghorror.com/i-shall-call-it-somethingmanager/)
-   [The Poetry of Function Naming](http://blog.stephenwolfram.com/2010/10/the-poetry-of-function-naming/)