-
Notifications
You must be signed in to change notification settings - Fork 2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Create best practise guidelines #2
base: master
Are you sure you want to change the base?
Changes from 3 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,72 @@ | ||||||||||||||||||
--- | ||||||||||||||||||
title: "Best Practice for R Package Creation" | ||||||||||||||||||
author: "Ellen Talbot - Locke Data" | ||||||||||||||||||
date: "`r format(Sys.time(), '%A %d %B %Y')`" | ||||||||||||||||||
output: | ||||||||||||||||||
html_document: | ||||||||||||||||||
code_folding: show | ||||||||||||||||||
highlight: pygments | ||||||||||||||||||
number_sections: yes | ||||||||||||||||||
theme: spacelab | ||||||||||||||||||
toc: yes | ||||||||||||||||||
toc_collapse: no | ||||||||||||||||||
toc_depth: 2 | ||||||||||||||||||
toc_float: yes | ||||||||||||||||||
css: !expr here::here('css', 'style.css') | ||||||||||||||||||
--- | ||||||||||||||||||
|
||||||||||||||||||
```{r setup, include = FALSE} | ||||||||||||||||||
knitr::opts_chunk$set(echo = TRUE, | ||||||||||||||||||
collapse = TRUE, | ||||||||||||||||||
fig.width = 8, | ||||||||||||||||||
fig.height = 6, | ||||||||||||||||||
dpi = 150, | ||||||||||||||||||
warning = FALSE, | ||||||||||||||||||
message = FALSE) | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
This is a high-level checklist for RECON packages that is backed by the broader information included in [rOpenSci Packages: Development, Maintenance, and Peer Review](https://devguide.ropensci.org/) and [R Packages: Organize, Test, Document, and Share Your Code](http://r-pkgs.had.co.nz/). Fundamentally, we want to write packages that people can use to support their work and make an impact. Our "audience" includes people with different levels of R skill and time to learn how to use a package so most of our guidelines are about helping you thinking about how you can make your package robust, error free, and accessible. | ||||||||||||||||||
|
||||||||||||||||||
# Package contents | ||||||||||||||||||
## README | ||||||||||||||||||
- Ensure the use of non-RECON user friendly language, try not to refer to internal processes etc. | ||||||||||||||||||
- Incude a clearly defined workflow and justification for using the package | ||||||||||||||||||
- Include an elevator pitch and examples of where and why the package has been used - this all improves trust for the user. | ||||||||||||||||||
- E.g. "You’re in DRC, have low internet connection, are working on X situation..." | ||||||||||||||||||
|
||||||||||||||||||
## Functions | ||||||||||||||||||
- Follow the coding rules in the `golden_rules` document | ||||||||||||||||||
- Functions should be clearly commented | ||||||||||||||||||
- Internal functions should be tagged as so | ||||||||||||||||||
- Commented out code should be removed to improve readability. | ||||||||||||||||||
- All functions both internal and external should have roxygen documentation | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For internal function, can you precise if you mean full roxygen doc (e.g. incl examples), or just |
||||||||||||||||||
- As a minimum internal functions should include a context e.g. #' This function is designed to... | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Typo: one white space too many |
||||||||||||||||||
- Avoid using personal/colloquial language when writing comments and context - non-RECON users need to understand too. | ||||||||||||||||||
- Examples for functions should appear in the roxygen comments rather than the README | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just to understand: are you discouraging worked examples from the |
||||||||||||||||||
|
||||||||||||||||||
## Tests | ||||||||||||||||||
- Tests should be written prior to the code. | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If easy, could you provide a link to some basics principles of TDD? |
||||||||||||||||||
- Basic tests should test defaults first and foremost. | ||||||||||||||||||
- Test coverage should be as comprehensive as possible | ||||||||||||||||||
|
||||||||||||||||||
## Quality checks | ||||||||||||||||||
Use packages like {devtools}, {lintr}, and {goodpractice} to ensure your code passes quality checks, correct spellings, and meets common formatting standards. | ||||||||||||||||||
|
||||||||||||||||||
```r | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Cool! :) |
||||||||||||||||||
devtools::check() | ||||||||||||||||||
goodpractice::gp() | ||||||||||||||||||
lintr::lint_package() | ||||||||||||||||||
devtools::spell_check() | ||||||||||||||||||
``` | ||||||||||||||||||
|
||||||||||||||||||
# Collaboration | ||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I believe a section on branch protection is missing, so I've taken the liberty to add it here:
Suggested change
|
||||||||||||||||||
|
||||||||||||||||||
## Contributing Guidelines | ||||||||||||||||||
- Contributing guidelines should be included in each package repo, there is a good example at `reportfactory/CONTRIBUTING.md`. | ||||||||||||||||||
|
||||||||||||||||||
## Issue and Pull Request Templates | ||||||||||||||||||
- Issue and PR templates should be included in each package repo, there is a good example at `reportfactory/.github`. | ||||||||||||||||||
|
||||||||||||||||||
**Guidelines and templates all improve the chances of you having a more manageable workload and a great relationship with helpful contributors!** | ||||||||||||||||||
|
||||||||||||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo: Include