-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path2025_poster.qmd
More file actions
154 lines (103 loc) · 5.52 KB
/
Copy path2025_poster.qmd
File metadata and controls
154 lines (103 loc) · 5.52 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
---
title: "openstatsguide: Checklist for Good Statistical Software Packages"
subtitle: "Developers Value Tests For Software Longevity"
author: "Alessandro Gasparini, Daniel Sabanés Bové, Nils Penard, Audrey Yeo Te-ying, on behalf of openstatsware"
bibliography: references.bib
mainfont: "Inter"
format:
typst:
background: "rgb(#D0F0C0)"
fig-format: "png"
fontsize: 35pt
mainfont: "Inter"
font-paths:
- "fonts/Fira_Code,Inter"
typst-font-paths:
- "fonts/Fira_Code,Inter"
papersize: a0
margin:
x: 2.5cm
y: 5.0cm
columns: 2
knitr:
opts_chunk:
dev: "svg"
include-before-body:
- text: |
#show heading: set text(font: "Fira Code", weight: "black", size: 50pt)
#show: title => {
text(font: "Fira Code", weight: "black", size: 50pt)[#title]
}
#show: author => {
text(font: "Inter", size: 32pt, weight: "bold")[#author]
}
#set text(font: "Inter")
#show bibliography: set text(size: 18pt)
#set bibliography(title: [References])
editor:
render-on-save: true
---
::: {.content-hidden when-format="typst"}
@ropensci_statsoftware_2021 @ropensci_devguide_2024 @pharmar_2020 @usethis_2024
@wickham_2023 @wickham_design @carpentries_2023 @gswe4rp_2024 @validation_2024
@sabanes_2023
:::
::: {.block fill=rgb("#FFCC00") inset="35pt" radius="40pt"}
# {width=15% fig-align="center"} *Scope*
We encourage developers of statistical software packages to follow this minimum set of good practices around:
> "**D**ocumentation, **V**ignettes, **T**ests, **F**unctions, **S**tyle, **L**ife cycle"
These keywords can be easily remembered with the mnemonic bridge sentence:
> "**D**evelopers **V**alue **T**ests **F**or **S**oftware **L**ongevity"
While the recommendations are rather generic, we focus on functional programming languages and give links to implementations in R, Python and Julia.
This guide primarily addresses developers of statistical packages.
Users interested in assessing the quality of existing statistical packages will find complementary "validation"-focused resources on the guide website.
:::
::: {.block fill=rgb("#F4F8D3") inset="40pt" radius="40pt"}
# {width=9% fig-align="center"} *Documentation*
… is important for both users and developers to understand all objects in your package, without reading and interpreting the underlying source code.
1. Use in-line comments to generate their corresponding documentation. {`roxygen2`}
2. Do also document internal functions and classes.
3. Add code comments for ambiguous or complex pieces of internal code.
:::
::: {.block fill=rgb("#FFCC00") inset="40pt" radius="40pt"}
# {width=10% fig-align="center"} *Vignettes*
… provide a comprehensive and long-form overview of your package’s functionality from a user point of view.
1. Provide an introduction vignette that opens up the package to new users.
2. Include deep-dive vignettes, including describing statistical methodology.
3. Host your vignettes on a dedicated website. {`pkgdown`}
:::
::: {.block fill=rgb("#F4F8D3") inset="40pt" radius="40pt"}
# {width=15% fig-align="center"} *Tests*
… are a fundamental safety net and development tool to ensure that your package works as expected, as you develop and use it.
1. Write unit tests for all functions/ classes in your package (“white box” testing).
2. Write functional tests for your user API (“black box” testing). {`testthat`}
3. In addition, ensure good coverage of your code with your tests as a final check. {`covr`}
:::
::: {.block fill=rgb("#FFCC00") inset="40pt" radius="40pt"}
# {width=10% fig-align="center"} *Functions*
… should be short, simple and enforce argument types with assertions.
1. Write short functions for a single and well defined purpose, with few arguments.
2. Use type hints declaring which arguments expect which type of input. {`roxytypes`}
3. Enforce types and other expected properties of function arguments with assertions. {`checkmate`}
:::
::: {.block fill=rgb("#F4F8D3") inset="40pt" radius="40pt"}
# {width=13% fig-align="center"} *Style*
… should be language idiomatic and enforced by style checks.
1. Use language idiomatic code and follow the “clean code” rules.
2. Use a formatting tool to automate code formatting. {`styler`}
3. Use a style checking tool to enforce a consistent and readable code style. {`lintr`}
:::
::: {.block fill=rgb("#FFCC00") inset="40pt" radius="40pt"}
# {width=10% fig-align="center"} *Lifecycle*
… management is crucial to build up your user base in a sustainable way.
Life cycle management is simplified by reducing dependencies, and should comprise a central code repository.
1. Reduce dependencies to simplify maintenance of your own package and depend on other packages that you trust and deem stable enough.
2. Track dependencies and pin their versions to produce consistent results and behaviours by using more system level that serves as a source of truth for all packages developers.
3. Maintain the change log and deprecate functionality before deleting it.
4. Use a central repository for version control and publication of a contributing guide to enable community contributions.
:::
# References
::: {.block fill=rgb("#FFFFFF") inset="40pt" radius="40pt"}
Scan the QR code to read the online version of openstatsguide:
{width=20% fig-align="center"}
:::