Checklist Program Code (Software) Publishing
When publishing software, it is useful to follow the advice below to make software as Findable, Accessible, Interoperable, and Reuseable (FAIR) as possible.
Program code can commonly be published using the same repositories as for publishing research data. Re3data.org provides an overview of repositories, which can help you locate a suitable repository for your code.
Consider the following when publishing code:
- Describe clearly in metadata and README-file the programming language(s) of your scripts (e.g. C#, Go, Javascript, Python, R), if applicable also with version.
- Do not put the README-file together with scripts (or datafiles) in a zip-file, but keep it separate (as .txt or .md – markdown), to be displayed directly in the repository interface, thereby allowing (re-)users to evaluate the content without first downloading the whole package.
- Place a brief explanatory comment at the start of every program [and possibly inherent version history], including a good example of how the program is used. [1]
- Decompose programs into smaller functions, that is a reusable section of software. Name functions, list their input parameters, and describe what information they produce. Functions make it easier to test and troubleshoot when things go wrong.[1]
- Avoid duplication. Write and re-use functions instead of copying and pasting code, and use data structures like lists instead of creating many closely related variables, e.g. create "score = (1, 2, 3)" rather than "score1", "score2", and "score3". [1]
- Document software dependencies and requirements explicitly so that mechanisms to access these exist. [1,2]
- Provide a simple example or test data set that users (including yourself) can run to determine whether the program is working and whether it gives a known correct output for a simple known input. [1]
- Submit code/scripts to a reputable DOI-issuing repository, just as you do with data. Your software is as much a product of your research as your articles and should be as easy for people to credit. DOIs for software are provided e.g. by Figshare and Zenodo, both integrating with GitHub. [1] For software code/scripts specifically related to climate research the Bolin Centre at Stockholm University has a local GitLab code repository instance that will issue DOIs on demand for fixed releases of submitted software scripts. See the Bolin Centre support site for information and help.
- We encourage all software produced in research projects to be published under an open-source license. Examples are found in this list: https://spdx.org/licenses/ [3]
- To benefit fully from possible tab completion, make all variable-, directory- and file names in to unique strings with distinct beginnings (so that no name is a substring of another in the same context). For directories and file names, use only the restricted character set [A-Za-z0-9-_.], with no white space inside.
[1] Wilson et al. (2017): Good enough practices in scientific computing.
[2] Lamprecht et al. (2020): Towards FAIR principles for research software.
[3] Akhmerov et al. (2019): Raising the Profile of Research Software.