Skip to contents

Explanation: Rhino style guide

Source: vignettes/explanation/rhino-style-guide.Rmd
rhino-style-guide.Rmd

Rhino follows the tidyverse style guide, with specific additional rules for box::use statements to enhance readability and maintainability of code. These rules are designed to work alongside tidyverse conventions, providing clarity and consistency when using box modules.

For more details on how to use box::use statements, see Explanation: Box modules.

For more details on how to configure linter rules in the .lintr file, see Configuring linters.

Explicit Import

For clarity and ease of tracking function origins, avoid using [...] for imports. Explicitly declare all packages, modules and functions.

# Good
box::use(
  infer[specify],
  shiny,
)

# Bad
box::use(
  infer[...],
  shiny[...],
)

observe() # Is it from {infer} or {shiny}?

Trailing Commas

Trailing commas in box::use statements are encouraged. They simplify line additions and reordering.

# Good
box::use(
  shiny,
)

# Bad
box::use(
  shiny
)

Separated Statements for Packages and Modules

Use separate box::use statements for importing packages and modules (R scripts) for better structure and readability.

# Good
box::use(
  rhino[log],
  shiny,
)

box::use(
  path/to/module,
)

# Bad
box::use(
  rhino[log],
  shiny,
  path/to/module,
)

Order of Imports

Order imports alphabetically to ease locating a specific import. This applies to both packages/modules and functions within them.

# Good
box::use(
  rhino,
  shiny[div, fluidPage],
)

# Bad
box::use(
  shiny[fluidPage, div],
  rhino,
)

Aliases

Aliases can be useful for long package/module and function names. Imports should still follow the alphabetical order of package/module names and function names.

# Good
box::use(
  z_pkg = rhino,
  shiny[div, a_fun = fluidPage],
)

# Bad
box::use(
  a_pkg = shiny,
  rhino[a_fun = react_component, log],
)

Number of Imports

Limit the number of functions imported from a module or package to 8. If more than 8 functions are needed, import the entire package and reference functions using package$function. Aliases can be used for convenience. Check box::use documentation for more details.

# Good
box::use(
  rhino[log],
  shiny,
)

# Bad
box::use(
  rhino[log],
  shiny[div, fluidPage, navbarPage, sidebarPanel, sidebarLayout, mainPanel, tabPanel, tabsetPanel, titlePanel],
)

Automated Styling of box::use() calls

As of Rhino version 1.10.0, format_r() includes styling for box::use() calls. This is provided by {box.linters} version >= 0.10.4. As with {styler}, carefully examine the styling results after performing automated styling on your code.

Automated styling covers some of the topics described above such as:

  • Separating box::use() calls for packages and local modules
  • Alphabetically sorting packages, modules, and functions.
  • Adding trailing commas
# Original
box::use(stringr[str_trim, str_pad], dplyr, app/logic/table)

# Styled
box::use(
  dplyr,
  stringr[str_pad, str_trim],
)

box::use(
  app/logic/table
)

Requirements

  • R version >= 4.3.0
  • box.linters version >= 0.10.4
  • treesitter package
  • treesitter.r package

How to use

  1. box::use() call styling is included when running format_r().
  2. It can also be separately executed by running one of the box.linters::style_* functions.

For more information on the abilities of {{box.linters}} styling functions refer to the styling functions documentation.