Style guide

The Hector package contains both R and C++ code. Hector’s model components are written in C++ and use Rcpp to pass information to the R, which gives Hector users the ability to run, manipulate, and visualize Hector results in R. Contributions to Hector’s R or C++ codebase must meet the respective requirements.

C++ Hector Code Base

Coding style:

• New C++ code should follow the LLVL coding standards

The Hector codebase is periodically reformatted using clang-format. For example, assuming that the working directory is the repository root:

# First, if needed:
brew install clang-format

# Important note: we do NOT want to touch `src/rcpp_constants.cpp` pr `src/rcpp_hector.cpp`
find src/ -name "*.c*" | grep -v rcpp_constants | clang-format -i
clang-format -i inst/include/*.h*

Other general principles:

• basic file intro at top of every file (see existing examples)
• line of dashes separating functions
• use ‘const’ when possible: on functions, parameters, variables
• methods should start with assertions on inputs
• try to use C++ STL or Boost data structures and functions (instead of rolling your own)

Unit testing:

• writing test case is part of writing code
• every method should have at least one test if possible
• every class/subunit should have a dedicated test group

Expected documentation:

• every method should have Doxygen comment header. Required tags:
  • \brief (always)
  • \param[in] (if any)
  • \param[out] (if any)
  • \returns (if returns a value)
  • \exception (if any throws or assertions)
• all but most trivial vars should have Doxygen comments in headers
• comments should generally say WHY not WHAT

R Hector Code Base

Some of the R code is generated by Rcpp code; do not edit these files by hand. These files all start with:

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: Numbers-Letters-Token

To make changes in those files, find the corresponding .cpp file and make changes there.

Coding style:

• follows the R package format and style guidelines
• R CMD checks should pass CRAN checks
• follows the R style guide
• R code should pass lintr::lint_package() (this is run as one of the package tests)

Expected documentation:

• use roxygen documentation for all functions, required tags:
  • @param to describe every function argument
  • @return a description of the object returned by the function
• clear and concise inline comments that describe WHY the code is doing what it does
• add a vignette or article when appropriate

Unit testing:

• add R package unit tests
• unit tests should be quick and use minimal (if needed) package data