Create best practise guidelines #2
Conversation
|
@thibautjombart @zkamvar Can you review &/| approve please? |
|
On it. |
best_practise.Rmd
Outdated
| # 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 |
best_practise.Rmd
Outdated
| - 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 | ||
| - As a minimum internal functions should include a context e.g. #' This function is designed to... |
There was a problem hiding this comment.
Typo: one white space too many
| - 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.
For internal function, can you precise if you mean full roxygen doc (e.g. incl examples), or just @param ?
best_practise.Rmd
Outdated
| - All functions both internal and external should have roxygen documentation | ||
| - As a minimum internal functions should include a context e.g. #' This function is designed to... | ||
| - 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.
Just to understand: are you discouraging worked examples from the README? I thought these were useful for people who wanted to get an idea of the package's main features at a glance, but happy to change.
| ## Quality checks | ||
| Use packages like {devtools}, {lintr}, and {goodpractice} to ensure your code passes quality checks, correct spellings, and meets common formatting standards. | ||
|
|
||
| ```r |
best_practise.Rmd
Outdated
| - Examples for functions should appear in the roxygen comments rather than the README | ||
|
|
||
| ## Tests | ||
| - Tests should be written prior to the code. |
There was a problem hiding this comment.
If easy, could you provide a link to some basics principles of TDD?
| devtools::spell_check() | ||
| ``` | ||
|
|
||
| # Collaboration |
There was a problem hiding this comment.
I believe a section on branch protection is missing, so I've taken the liberty to add it here:
| # Collaboration | |
| # Collaboration | |
| ## Branches | |
| The master branch should represent a stable state in the repository and should be protected from direct pushes and force-pushes using GitHub's [branch protection rules](https://help.github.com/en/github/administering-a-repository/about-protected-branches). Contributions to the master branch should only be made via Pull Requests with the exception of the initial few commits before user testing. | |
| Pull requests should pass quality checks from continuous integration before merging. |
|
One more thing regarding this: it should mesh with the guidelines found on the website: https://www.repidemicsconsortium.org/resources/guidelines/ |
|
@zkamvar incorporated 👍 |
Best practise document for new and existing packages - issue #1