12 Good practices and advice

This section contains some general advice about package development. It may be opinionated in places so decide which things work for you.

12.1 Design advice

  • Compatibility - Make your package compatible with how your users already work. If there are data structure that are commonly used write your functions to work with those rather than having to convert between formats.
  • Ambition - It’s easy to get carried away with trying to make a package that does everything but try to start with whatever is most important/novel. This will give you a useful package as quickly and easily as possible and make it easier to maintain in the long run. You can always add more functionality later if you need to.
  • Messages - Try to make your errors and messages as clear as possible and other advice about how to fix them. This can often mean writing a check yourself rather than relying on a default message from somewhere else.
  • Check input - If there are restrictions on the values parameters can take check them at the beginning of your functions. This prevents problems as quickly as possible and means you can assume values are correct in the rest of the function.
  • Useability - Spend time to make your package as easy to use as possible. Users won’t know that your code is faster or produces better results if they can’t understand how to use your functions. This includes good documentation but also things like having good default values for parameters.
  • Naming - Be obvious and consistent in how you name functions and parameters. This makes it easier for users to guess what they are without looking at the documentation. One option is to have a consistent prefix to function names (like usethis does) which makes it obvious which package they come from and avoids clashes with names in other packages.

12.2 Coding style

Unlike some other languages R is very flexible in how your code can be formatted. Whatever coding style you prefer it is important to be consistent. This makes your code easier to read and makes it easier for other people to contribute to it. It is useful to document what coding style you are using. The easiest way to do this is to adopt a existing style guide such as those created for the Tidyverse (https://style.tidyverse.org/) or Google (https://google.github.io/styleguide/Rguide.html) or this one by Jean Fan (https://jef.works/R-style-guide/). If you are interested in which styles people actually use check out this analysis presented at useR! 2019 https://github.com/chainsawriot/rstyle. When contibuting to other people’s projects it is important (and polite) to conform to their coding style rather than trying to impose your own.

If you want to make sure the style of your package is consistent there are some packages that can help you do that. The lintr package will flag any style issues (and a range of other programming issues) while the styler package can be used to reformat code files. The goodpractice package can also be used to analyse your package and offer advice. If you are more worried about problems with the text parts of your package (documentation and vignettes) then you can activate spell checking with usethis::use_spell_check().

12.3 Version control

There are three main ways to keep tracks of changes to your package:

  1. Don’t keep track
  2. Save files with different versions
  3. Use a version control system (VCS)

While it can be challenging at first to get your head around git (or another VCS) it is highly recommended and worth the effort, both for packages and your other programming projects. Here are something of the big benefits of having your package in git:

  • You have a complete record of every change that has been made to the package
  • It is easy to go back if anything breaks or you need an old version for something
  • Because of this you don’t have to worry about breaking things and it is easier to experiment
  • Much easier to merge changes from collaborators who might want to contribute to your package
  • Access to a variety of platforms and services built around this technology, for example installing your package, hosting a package website and continuous integration (see below)

As mentioned earlier a great way to get started with git for R projects is Jenny Bryan’s “Happy Git with R” (https://happygitwithr.com) but there are many more tutorials and workshops available.

12.4 Continuous integration

During the workshop we showed you how to run checks and tests on your package but this will only tell you if they pass on your particular computer and platform. Continuous integration services can be used to automatically check your package on multiple platforms whenever you make a significant change to your package. They can be linked to your repository on code sharing websites like GitHub and whenever you push a new version they will run the checks for you. This is similar to what CRAN and Bioconductor do for their packages but we doing it yourself you can be more confident that you won’t run into issues when you submit your package to them. If your package isn’t on one of the major repositories it helps give your users confidence that it will be reliable. Some continuous integration services are:

Each of these has a free service at it is easy to set them up for your package using the appropriate usethis::use_CI_SERVICE() function.