Note: this document is work in progress! Please send comments / suggestions using disqus, by posting issues or via pull requests. The file generating this page is there.

This document provides guidelines for package development which are meant to promote clearer, robust, maintainable, and well-documented code. It borrows largely from the rOpenSci onboarding guidelines and from this post on the RECON forum. See list of contributors for more information on people who shaped this.

Package development guidelines

We recommend following the rOpenSci package development guidelines, with the following additions / changes:

  • RECON does not use any package submission system. If you would like your package to integrate RECON, be in touch with us directly (click on email link at the bottom of this page).

  • Packages should be hosted on github, or a similar platform with a (ideally, distributed) version control system; we recommend keeping the master branch as functional, and using other branches for more adventurous changes.

  • Packages should be submitted to a goodpractice run to detect possible issues.

  • The README.Rmd should provide an overview of the main functionalities of the package, and point to more detailed resources (vignettes, tutorials, open-access publications) where relevant.

  • Vignettes are strongly recommended for more detailed documentation, including worked examples, details of analyses and methods, customisation of graphics, and object classes. The Rmarkdown (.Rmd) format is preferred to Sweave (.Rnw) as it is easier to convert to .html pages.

  • We strongly recommend the use of roxygen2 for documentation, as it makes documentation easier to maintain.

  • We encourage the use of “::” when importing functions from non-core packages, as it makes dependencies on foreign code more visible (and avoids using @importFrom tags).

  • We encourage the use of pkgdown to generate a website for the package. For an example, see the incidence package and its website.

Credits

Besides the rOpenSci whose guidelines we largely adopted, the following people contributed to these guidelines; in alphabetic order:

  • Gabor Csardi
  • Rich Fitzjohn
  • Thibaut Jombart
  • Noam Ross