Skip to contents

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:

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:

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