16.2 Title, description, details

16.2.1 Title recommendations

  1. Sentence case
  2. not end in a full stop
  3. followed by a blank line
  4. succinct description of function

Bad titles:

  • str_detect(): Detect the presence or absence of a pattern in a string
  • str_extract(): Extract matching patterns from a string
  • str_locate(): Locate the position of patterns in a string
  • str_match(): Extract matched groups from a string

Good titles:

  • mutate(): Create, modify, and delete columns
  • summarise(): Summarize each group to fewer rows
  • filter(): Subset rows using column values
  • select(): Subset columns using their names and types
  • arrange(): Arrange rows by column values

16.2.2 Description recommendation

  1. summarize goal of the function in single paragraph
  2. Explicitly tag @description if multi-paragraph (or just need an empty line)
  3. Write description after you’ve come back and forgot what your function does

16.2.3 Details recommendation

  1. most functions don’t need this
  2. use informative markdown headings